The short answer
NPHIES, the National Platform for Health Information Exchange Services, is Saudi Arabia’s central hub for health insurance transactions between providers and insurers. Its Healthcare Financial Services implementation guide, published by HL7 Saudi Arabia on FHIR R4, defines messages for eligibility, prior authorization, claims, payments, polling and status.1 The hub validates every message and rejects invalid ones, but it doesn’t adjudicate claims.2 Messages go to a $process-message endpoint over HTTPS, with both sides authenticating each other, within limits of 60 seconds per session, 10 MB per message and 200 claims per batch.3
Deedglass
A denial needs two different people
Drafted by AI
Prior authorization
MRI, lower back · draft: deny
Request 7781 · made-up member
A denial needs two different people
Approvals · 1 of 2
- RIR. IyerNurse reviewerApproved
- AMDr. A. MehtaMedical directorTo decide
Runs only after both approve
- One person can’t approve twice
- One refusal is final
- An agent can never approve itself
What NPHIES is
The guide’s introduction explains the history. The Council of Health Insurance (CHI) and the Ministry of Health started separate programs for financial and clinical exchange around 2012; they were later combined under the name nphies.2 Today, the guide says, CHI regulates 6,600 provider organisations, 28 insurers and 8 TPAs serving about 14.1 million beneficiaries, as of October 2025.2
The guide’s own metrics table lists 292 million transactions in 2024 and 96% of authorizations adjudicated within 30 minutes.2 Those are the guide’s figures, not ours.
The design choice that matters most: nphies is a single hub. Providers don’t send claims to insurers directly. Everything goes through the platform, which validates format, coding and business rules, then delivers to the insurer or holds the message until the insurer is available.2 The guide describes it as “processing and validating (not adjudicating).” Insurers still decide claims.
The message types
The guide groups exchanges into use cases.1
| Use case | What it does |
|---|---|
| Eligibility | Checks a patient’s coverage with an insurer |
| Prior and advanced authorization | Asks the insurer to approve services before they happen |
| Claims and claim batches | Submits claims, singly or in batches |
| Payment reconciliation and notification | Tells providers what was paid |
| Information request and submission | Lets insurers ask for, and providers send, more information |
| Cancel, status, polling, error notice | Manages messages already sent |
The guide is marked as version 1.0.0, a trial-use edition, and the index page shows it as a draft dated 3 December 2025.1 Check the portal for the current version before you build.
How a message moves
NPHIES uses FHIR messaging, not plain REST. Each exchange is a message Bundle posted to a $process-message endpoint. The guide describes four patterns: full cycle from provider through nphies to insurer and back; provider to nphies; insurer to nphies; and nphies to insurer.3
In the full cycle, the provider opens an HTTPS session with nphies and both sides authenticate each other. nphies validates the message, stores it in a queue and, if the insurer is online, forwards it and waits for the insurer’s response within the same session.3 If the insurer can’t be reached in time, nphies returns a response saying the message is queued, and the provider retrieves the final answer later by resending or polling.3
The guide sets hard limits:3
| Limit | Value |
|---|---|
| Communication session up time | 60 seconds |
| Message size | 10 MB |
| Claims per batch | 200 |
| Messages per poll | 100 |
The 60-second limit shapes your software. A provider system that waits on a slow internal process before sending, or an insurer system that takes minutes to respond, will hit the queue path. Polling and the queued response aren’t edge cases; they’re part of normal operation.
Duplicates and retries
Because sessions can time out and senders retry, the guide is strict about duplicates. Every receiver checks whether it has seen a transaction before, using the MessageHeader.id and the identifier on the focal resource. For claims and prior authorizations that’s Claim.identifier, a combination of system and value supplied by the provider.3
The rules, simplified:
- Same MessageHeader.id, same identifier, same content: a duplicate. You get the stored response back, and nphies doesn’t forward it again.3
- New MessageHeader.id but an identifier you’ve already used: an error.3
- Same MessageHeader.id with a new identifier: an error.3
This is the same problem any retrying client faces, including AI agents that retry tool calls. If your retry logic generates a fresh MessageHeader.id or a fresh claim identifier on each attempt, you either get errors or, worse, a second claim. Our post on an agent that retried and wrote twice and the one on FHIR conditional create duplicates cover the general pattern.
What errors look like
The error handling page separates transport success from business success. If messages were exchanged, the HTTP status is 200 OK, even when the response says the request had errors.4
| What the sender sent | What comes back |
|---|---|
| Unparsable message | OperationOutcome, status 300+4 |
| Parsable but structurally invalid | OperationOutcome, status 300+4 |
| Valid structure, invalid content | Business response listing errors, 200 OK4 |
| Insurer unreachable in time | Business response marked queued, 200 OK4 |
The trap is treating 200 as “accepted.” A 200 can carry a claim response full of errors, or a queued status with no decision yet. Your code has to read the response body every time.
Where AI tools fit
Hospitals and insurers in the region are adding AI to coding, claim preparation and pre-authorization review. NPHIES doesn’t change because an AI drafted the claim, but it raises the cost of mistakes:
- Validation catches format, not intent. nphies rejects invalid structure and codes, but a well-formed claim with the wrong service still goes through to the insurer.2
- Retries need stable identifiers. An AI tool that resubmits after a timeout must reuse the same MessageHeader.id and Claim.identifier.3
- Read the response, not the status code. A 200 with errors in the body is not a submitted claim.4
- Keep your own record. Store what your system sent, what came back, and who or what approved it before sending. When a claim is disputed, that record is what you have.
For comparison with India’s claims exchange, see our NHCX post; for the US prior authorization guides, see Da Vinci CRD, DTR and PAS. Our insurers page shows how agent actions on claims get recorded and checked.
A checklist for integrators
- Build against the current IG on the nphies portal; note the version.1
- Use FHIR message Bundles to
$process-messageover HTTPS with mutual authentication.3 - Design for the 60-second session and implement polling from day one.3
- Keep messages under 10 MB and batches under 200 claims.3
- Generate MessageHeader.id and Claim.identifier once and reuse them on retry.3
- Parse every response body; never treat 200 as success on its own.4
- Log each sent message and response with the approver, human or automated.
Questions people ask
Does NPHIES use FHIR?
Yes. The financial services guide is built on FHIR R4.0.1 and published by HL7 Saudi Arabia.1
Does NPHIES approve claims?
No. It validates and routes messages; insurers adjudicate.2
What happens if the insurer doesn’t answer in time?
nphies queues the message and returns a queued response; the provider polls or resends to get the result.3
This post summarises the NPHIES implementation guide as published on its portal; it isn’t integration advice for a specific payer. To see FHIR writes checked by read-back in your browser, open the playground; to grade what an agent can reach on your own machine, run npx deedglass scan (the grade, explained).
Written with AI assistance and checked against our claims register.