NPHIES Integration Toolkit

1. Eligibility Check

Verify patient is covered before providing service.

POST /CoverageEligibilityRequest
{
  "resourceType": "CoverageEligibilityRequest",
  "patient": "Patient/12345",
  "insurer": "Organization/BUPA",
  "servicedDate": "2026-05-14",
  ...
}

2. Pre-Authorization

For major procedures before performing them.

POST /Claim?use=preauthorization
{
  "resourceType": "Claim",
  "use": "preauthorization",
  ...
}

3. Claim Submission

After service, submit the claim.

POST /Claim
{
  "resourceType": "Claim",
  "patient": "Patient/12345",
  "diagnosis": [{...ICD-10 code...}],
  "item": [{...CPT codes + drugs...}],
  ...
}

4. Payment Reconciliation

Receive remittance from payer.

GET /PaymentReconciliation?_id=PR-12345

1. Register hospital/clinic in CCHI portal
2. Obtain Provider ID from NPHIES
3. Generate X.509 certificate for digital signature
4. Register certificate in NPHIES portal
5. Test in NPHIES Sandbox environment
6. Setup ICD-10 mapping table (if running ICD-9)
7. Setup SFDA drug codes database (40K+ drugs)
8. Setup HL7 → FHIR converter (if LIS/RIS present)
9. Test end-to-end (eligibility → claim → payment)
10. Go-live

ICD-9 → ICD-10

Full mapping table available from ZATCA + WHO. Softloomer NPHIES module comes with 14K+ mappings preloaded.

SFDA Drug Codes

Error 401: Authentication Failed

Cause: Certificate expired or wrong client_id. Fix: renew certificate + verify NPHIES portal registration.

Error 422: Validation Failed

Cause: FHIR resource format wrong. Fix: validate against NPHIES FHIR Implementation Guide.

Error 429: Rate Limit Exceeded

Cause: More than 100 requests/minute. Fix: implement queue + exponential backoff.

Claim Rejected: Missing ICD-10

Cause: Diagnosis not in ICD-10 format. Fix: mapping table conversion before submission.

• Cache eligibility results for 24 hours — they won't change
• Batch claim submission — submit in chunks of 100 instead of one by one
• Async processing — pre-authorization takes 1-3 days, do polling instead of sync waiting
• Webhook integration — NPHIES supports webhooks for payment events
• Monitoring — track submission success rate, rejection reasons, processing time