NPHIES Developer Integration Guide: Building Saudi Arabia's Health Data Network Compliance

Saudi Arabia's NPHIES (National Platform for Health Information Exchange and Services) is one of the most technically ambitious healthcare interoperability initiatives in the world. Launched as part of Vision 2030's health sector transformation, NPHIES mandates standardised electronic data exchange between healthcare providers and insurance companies across the Kingdom — covering eligibility verification, prior authorisation, and claims processing for every insured patient encounter.

For developers building healthcare technology in Saudi Arabia — whether for hospital groups, insurance companies, or health technology startups — NPHIES integration is not optional. This guide provides a practical technical reference for NPHIES implementation based on production integration work with KSA healthcare organisations.

NPHIES Architecture Overview

NPHIES is operated by the National Centre for Health Information (NCHI), an arm of Saudi Arabia's Ministry of Health. It functions as a national health data network — a hub through which providers and payers exchange structured clinical and financial data using FHIR R4.

The core NPHIES workflows are:

1. Eligibility Verification (CoverageEligibilityRequest/Response) Before treating an insured patient, providers submit an eligibility check to NPHIES. NPHIES routes the request to the relevant insurance company and returns the patient's coverage details, benefit limits, and co-payment requirements. This replaces phone-based eligibility verification.

2. Prior Authorisation (Claim with use: preauthorization) For services requiring prior approval, providers submit a PA request through NPHIES. The insurer reviews and responds with approval, partial approval, or denial. NPHIES tracks PA status and expiry.

3. Claims Submission (Claim with use: claim) After service delivery, providers submit electronic claims through NPHIES. Claims reference the prior authorisation number where applicable. Insurers adjudicate and respond with ClaimResponse resources.

4. Communication (Communication/CommunicationRequest) Additional documentation requests, supporting documents for PA, and queries between providers and payers flow through NPHIES as Communication resources.

NPHIES FHIR R4 Implementation

NPHIES uses FHIR R4 with Saudi-specific profiles and extensions published in the NPHIES Implementation Guide. These profiles differ significantly from international standards (US Core, IPS) and require careful implementation.

Key NPHIES-Specific FHIR Extensions

NPHIES introduces extensions not present in base FHIR R4 to capture Saudi-specific data requirements:

{
  "url": "http://nphies.sa/fhir/ksa/nphies-fs/StructureDefinition/extension-episode",
  "valueIdentifier": {
    "system": "http://nphies.sa/identifier/episode",
    "value": "EP-2025-001234"
  }
}

The NPHIES IG defines extensions for:

• Episode of care identifier — links multiple encounters for the same clinical episode
• Speciality — the treating speciality using the NPHIES speciality code system
• Outcome of visit — the final outcome of the outpatient encounter
• Eligibility response reference — linking a claim to its originating eligibility check

Saudi Patient Identifier System

Patient identification in NPHIES uses Saudi-specific national identifiers:

• National ID (Huwiyya) — 10-digit identifier for Saudi nationals, system: http://nphies.sa/identifier/nationalid
• Iqama — 10-digit residence permit number for expatriates, system: http://nphies.sa/identifier/iqama
• Border Number — for individuals without National ID or Iqama
• Visa Number — for visitors

All Patient resources submitted to NPHIES must include one of these identifiers. Your patient registration system must reliably capture and validate the National ID or Iqama at registration.

The National ID has a specific validation algorithm (Luhn-based with Saudi-specific rules). Validate at registration to prevent submission failures:

public static bool ValidateSaudiNationalId(string nationalId)
{
    if (nationalId.Length != 10) return false;
    if (!nationalId.All(char.IsDigit)) return false;
    
    // Must start with 1 (Saudi national) or 2 (expatriate Iqama)
    var prefix = nationalId[0];
    if (prefix != '1' && prefix != '2') return false;
    
    // Luhn algorithm check
    int sum = 0;
    for (int i = 0; i < 10; i++)
    {
        int digit = int.Parse(nationalId[i].ToString());
        if (i % 2 == 0)
        {
            digit *= 2;
            if (digit > 9) digit -= 9;
        }
        sum += digit;
    }
    
    return sum % 10 == 0;
}

Eligibility Verification Implementation

The eligibility check (CoverageEligibilityRequest) is typically the first NPHIES interaction in the patient visit workflow. It must be submitted before providing services to confirm current coverage.

CoverageEligibilityRequest Structure

{
  "resourceType": "CoverageEligibilityRequest",
  "id": "eligibility-req-001",
  "meta": {
    "profile": ["http://nphies.sa/fhir/ksa/nphies-fs/StructureDefinition/eligibility-request"]
  },
  "status": "active",
  "purpose": ["benefits", "validation"],
  "patient": {
    "reference": "Patient/patient-001"
  },
  "created": "2025-11-15T09:00:00+03:00",
  "provider": {
    "reference": "Organization/provider-001"
  },
  "insurer": {
    "reference": "Organization/insurer-001"
  },
  "insurance": [
    {
      "focal": true,
      "coverage": {
        "reference": "Coverage/coverage-001"
      }
    }
  ],
  "item": [
    {
      "category": {
        "coding": [
          {
            "system": "http://nphies.sa/terminology/CodeSystem/benefit-category",
            "code": "1"
          }
        ]
      },
      "productOrService": {
        "coding": [
          {
            "system": "http://nphies.sa/terminology/CodeSystem/service-type",
            "code": "AMB"
          }
        ]
      }
    }
  ]
}

The response (CoverageEligibilityResponse) contains the patient's benefit information, applicable co-payment amounts, and any benefit limitations relevant to the requested service category.

Handling Eligibility Response

public class EligibilityHandler
{
    public EligibilityResult ProcessResponse(CoverageEligibilityResponse response)
    {
        var result = new EligibilityResult();
        
        result.IsEligible = response.Disposition?.Contains("eligible") ?? false;
        
        foreach (var insurance in response.Insurance ?? Enumerable.Empty<CoverageEligibilityResponse.InsuranceComponent>())
        {
            foreach (var item in insurance.Item ?? Enumerable.Empty<CoverageEligibilityResponse.ItemsComponent>())
            {
                result.Benefits.Add(new BenefitDetail
                {
                    Category = item.Category?.Coding?.FirstOrDefault()?.Code,
                    NetworkStatus = item.Network?.Coding?.FirstOrDefault()?.Code,
                    InNetworkCopay = item.Benefit
                        .FirstOrDefault(b => b.Type?.Coding?.Any(c => c.Code == "copay") ?? false)
                        ?.Allowed as Money
                });
            }
        }
        
        return result;
    }
}

Prior Authorisation Implementation

Prior authorisation is the most complex NPHIES workflow. The PA request submits clinical justification for a service, and the insurer responds with approval or denial.

PA Claim Request Structure

PA requests use the FHIR Claim resource with use: preauthorization:

{
  "resourceType": "Claim",
  "meta": {
    "profile": ["http://nphies.sa/fhir/ksa/nphies-fs/StructureDefinition/prior-auth-request"]
  },
  "status": "active",
  "type": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/claim-type",
        "code": "professional"
      }
    ]
  },
  "use": "preauthorization",
  "patient": { "reference": "Patient/patient-001" },
  "created": "2025-11-15T09:15:00+03:00",
  "insurer": { "reference": "Organization/insurer-001" },
  "provider": { "reference": "Organization/provider-001" },
  "priority": {
    "coding": [{ "code": "normal" }]
  },
  "insurance": [
    {
      "sequence": 1,
      "focal": true,
      "coverage": { "reference": "Coverage/coverage-001" }
    }
  ],
  "diagnosis": [
    {
      "sequence": 1,
      "diagnosisCodeableConcept": {
        "coding": [
          {
            "system": "http://hl7.org/fhir/sid/icd-10-am",
            "code": "J18.9",
            "display": "Pneumonia, unspecified organism"
          }
        ]
      }
    }
  ],
  "item": [
    {
      "sequence": 1,
      "careTeamSequence": [1],
      "diagnosisSequence": [1],
      "productOrService": {
        "coding": [
          {
            "system": "http://nphies.sa/terminology/CodeSystem/procedure-code",
            "code": "99233"
          }
        ]
      },
      "servicedDate": "2025-11-15",
      "quantity": {
        "value": 3,
        "unit": "days"
      },
      "unitPrice": {
        "value": 500.00,
        "currency": "SAR"
      }
    }
  ]
}

Saudi Clinical Coding: ICD-10-AM

One of the most distinctive aspects of NPHIES is the use of ICD-10-AM — the Australian Modification of ICD-10. This differs from the US ICD-10-CM used in American FHIR implementations and from the international ICD-10-WHO edition.

The FHIR system URI for ICD-10-AM in NPHIES is: http://hl7.org/fhir/sid/icd-10-am

Key differences between ICD-10-AM and ICD-10-CM:

• Different chapter structures for certain condition groups
• Different procedure code system (Australian Classification of Health Interventions, ACHI — separate from CPT)
• Different sequencing rules for principal and additional diagnoses

If your EMR uses ICD-10-CM (common for US-origin systems deployed in KSA), you need a terminology mapping layer to convert ICD-10-CM codes to their ICD-10-AM equivalents. This is not a trivial one-to-one mapping — many codes differ between the two editions.

PA Status Polling

After submitting a PA request, the insurer responds asynchronously. NPHIES delivers the response via:

1. Webhook notification — if your endpoint is registered with NPHIES
2. Polling — query the ClaimResponse resource by PA number

For production systems, webhooks are preferred. Implement an NPHIES-compatible endpoint that:

• Accepts HTTP POST from NPHIES
• Validates the NPHIES signature header
• Processes the ClaimResponse or Task resource
• Returns HTTP 200 within 5 seconds (process asynchronously)

Claims Submission

After service delivery, claims are submitted referencing the approved PA (where applicable):

{
  "resourceType": "Claim",
  "use": "claim",
  "related": [
    {
      "claim": { "reference": "Claim/prior-auth-claim-001" },
      "relationship": {
        "coding": [
          {
            "code": "prior",
            "display": "Prior Claim"
          }
        ]
      }
    }
  ]
}

The related element links the claim to the original PA claim, allowing the insurer to adjudicate against the approved PA.

NPHIES Infrastructure Architecture

Message Submission via Bundle

All NPHIES transactions are submitted as FHIR Bundles. The bundle wraps the primary resource (Claim, CoverageEligibilityRequest) with all referenced resources:

{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": [
    {
      "fullUrl": "http://your-facility.sa/fhir/Claim/claim-001",
      "resource": { /* Claim resource */ },
      "request": {
        "method": "POST",
        "url": "Claim"
      }
    },
    {
      "fullUrl": "http://your-facility.sa/fhir/Patient/patient-001",
      "resource": { /* Patient resource */ },
      "request": {
        "method": "POST",
        "url": "Patient",
        "ifNoneExist": "identifier=http://nphies.sa/identifier/nationalid|1012345678"
      }
    }
  ]
}

Error Handling and NPHIES Response Codes

NPHIES returns specific OperationOutcome error codes for rejected submissions. The most common:

| Error Code | Meaning | Resolution | |-----------|---------|-----------| | NPHIES-001 | Invalid national ID format | Validate and correct the patient's national ID | | NPHIES-002 | Duplicate submission | Check submission idempotency keys | | NPHIES-003 | Invalid ICD-10-AM code | Verify the diagnosis code against the ICD-10-AM code set | | NPHIES-004 | Provider not found | Verify the provider's NPHIES registration | | NPHIES-005 | Coverage not active | Eligibility check returned inactive coverage | | NPHIES-006 | PA expired | The referenced PA has expired; submit a new PA |

Implement specific error handlers for each NPHIES error code — the resolution action differs for each.

Retry Logic and Idempotency

NPHIES API calls may fail due to transient network issues or NPHIES platform maintenance. Implement:

public class NphiesSubmissionService
{
    private readonly IAsyncPolicy<HttpResponseMessage> _retryPolicy;
    
    public NphiesSubmissionService()
    {
        _retryPolicy = Policy<HttpResponseMessage>
            .Handle<HttpRequestException>()
            .OrResult(r => (int)r.StatusCode >= 500)
            .WaitAndRetryAsync(
                3,
                retryAttempt => TimeSpan.FromSeconds(Math.Pow(2, retryAttempt)),
                onRetry: (outcome, delay, attempt, context) =>
                {
                    _logger.LogWarning(
                        "NPHIES submission retry {Attempt} after {Delay}s: {Error}",
                        attempt, delay.TotalSeconds,
                        outcome.Exception?.Message ?? outcome.Result.StatusCode.ToString()
                    );
                });
    }
    
    public async Task<ClaimResponse> SubmitClaimAsync(Bundle claimBundle, string idempotencyKey)
    {
        var request = new HttpRequestMessage(HttpMethod.Post, "/fhir/r4/Claim");
        request.Headers.Add("X-Idempotency-Key", idempotencyKey);
        request.Content = JsonContent.Create(claimBundle);
        
        var response = await _retryPolicy.ExecuteAsync(() => _httpClient.SendAsync(request));
        
        // Handle response
    }
}

The X-Idempotency-Key header ensures that duplicate submissions (from retry logic) are detected by NPHIES and return the original response rather than creating duplicates.

Data Residency and Security Requirements

NDMO Data Residency

Saudi Arabia's National Data Management Office (NDMO) requires that government-classified data — which includes national health data — remain within the Kingdom. Azure's Qatar Central region is the currently approved option for many KSA healthcare deployments. The new Azure Saudi Arabia regions (when generally available) will provide in-Kingdom data residency.

For NPHIES specifically, all patient health data processed through your integration must be stored in a NDMO-compliant cloud region or on-premises infrastructure within the Kingdom.

SDAIA PDPL Compliance

The Saudi Personal Data Protection Law (PDPL), enforced by SDAIA, governs patient data handling. NPHIES integration involves processing sensitive personal health data; your system must:

• Have a documented lawful basis for processing health data (typically "necessary for healthcare purposes")
• Implement data minimisation — only transmit the data required for each NPHIES transaction
• Enable patient data access rights — patients can request copies of their submitted health data
• Implement data retention limits — do not retain NPHIES transaction data longer than required by MOH regulations

Testing Against NPHIES Sandbox

NPHIES provides a sandbox environment for integration testing. To access it:

1. Register your organisation with NCHI (National Centre for Health Information)
2. Submit your integration specification — describe the workflows you are implementing and the FHIR profiles you are targeting
3. Receive sandbox credentials — NCHI provides OAuth 2.0 client credentials and the sandbox endpoint URL
4. Run test scenarios — NCHI may provide mandatory test scenarios that must be passed before production access is granted

Test scenarios typically include:

• Successful eligibility check for an active patient
• Eligibility check for an inactive patient (testing error response handling)
• PA submission and approval (positive path)
• PA submission and denial (testing denial response handling)
• Claims submission with approved PA reference
• Claims submission for a service not requiring PA

Timeline and Complexity Expectations

A complete NPHIES integration (eligibility, PA, claims) for a hospital or clinic typically takes:

• Weeks 1–3: NCHI registration, specification review, clinical coding assessment (ICD-10-AM mapping), and architecture design
• Weeks 4–8: Integration development — eligibility, PA, and claims workflows
• Weeks 9–11: NPHIES sandbox testing and error remediation
• Week 12: Clinical validation with billing team (are submitted codes and amounts correct?)
• Weeks 13–14: NCHI production access approval and go-live preparation
• Week 15–16: Phased production go-live with monitoring

Insurance company (payer-side) NPHIES implementations are typically more complex — receiving and processing PA and claims from multiple provider organisations, implementing adjudication logic, and returning ClaimResponse resources — and should budget 4–6 months.

Summary

NPHIES integration requires:

1. Understanding of Saudi-specific FHIR R4 profiles — not just base FHIR or US Core
2. ICD-10-AM clinical coding — different from both ICD-10-CM and ICD-10-WHO
3. Saudi patient identity handling — National ID and Iqama validation
4. Complete eligibility, prior authorisation, and claims workflows
5. NDMO-compliant data residency infrastructure (Qatar Central or KSA regions)
6. SDAIA PDPL compliance for patient data handling

The regulatory consequence of non-compliance is real — CCHI can delay reimbursement processing for non-compliant providers, and MOH can impose licence conditions. Starting well ahead of regulatory deadlines and working with developers who have Saudi-specific NPHIES experience is the highest-leverage investment you can make in your KSA market technology strategy.

For technical guidance on your NPHIES integration, book a free consultation.