Claim Scrubber — Integration Guide

What it does

You send a claim before submitting it to the payer. We answer with everything that would get it rejected — an invalid or unspecified diagnosis, a procedure code that is not in the CHI SBS list, a duplicate line, a drug the Saudi formulary does not license for that diagnosis, a missed filing deadline.

The check runs against the full CHI SBS V3 procedure list, the Saudi drug formulary (40,952 drug-to-diagnosis rules) and the diagnosis reference. Typical response time is under half a second.

Getting started

1. We create an account for your organisation and issue you an API key.
2. Store the key somewhere your application can read it. It is shown once and cannot be recovered — if it is lost we issue a new one.
3. Call the endpoint below and read the response. That is the whole integration.

Base URL   https://icdsbs.com/api/v1

Everything lives under /api/v1. When a breaking change is ever needed it will appear at /api/v2 and v1 will keep working — we will not change the meaning of an existing field underneath you.

Authentication

Send your key in the X-API-Key header on every request.

# check that your key works — start here
curl -H "X-API-Key: sk_live_your_key_here" \
     https://icdsbs.com/api/v1/scrub/rules

A key carries scopes. Most integrations get all three:

Option A — send a FHIR Claim (recommended)

Send the same Claim resource you are about to submit to NPHIES. We return a standard OperationOutcome.

POST /api/v1/scrub/fhir/Claim/$scrub

curl -X POST "https://icdsbs.com/api/v1/scrub/fhir/Claim/\$scrub" \
  -H "X-API-Key: sk_live_your_key_here" \
  -H "Content-Type: application/fhir+json" \
  -d @claim.json

Accepts a Claim on its own, or a Bundle containing the Claim plus Patient, Coverage and Organization. References resolve from bundle entries or from contained. What we read:

A coding system containing medication, drug, atc, rxnorm, ndc, sfda or scientific marks the line as a drug; anything else is treated as a procedure and checked against SBS.

What comes back

{
  "resourceType": "OperationOutcome",
  "issue": [{
    "severity": "error",
    "code": "business-rule",
    "details": {
      "coding": [{ "system": "https://icdsbs.com/fhir/CodeSystem/scrub-rules",
                    "code": "RX002" }],
      "text": "IBUPROFEN is not licensed in the formulary for N41.0."
    },
    "diagnostics": "Add the diagnosis that justifies it, or switch to a licensed alternative.",
    "expression": ["Claim.item[0].productOrService"]
  }],
  "extension": [{
    "url": "https://icdsbs.com/fhir/StructureDefinition/scrub-summary",
    "extension": [
      { "url": "verdict",      "valueCode": "would_reject" },
      { "url": "amountAtRisk", "valueMoney": { "value": 24.0, "currency": "SAR" } },
      { "url": "findingCount", "valueInteger": 1 }
    ]
  }]
}

expression is the field to build your UI on. It is a FHIRPath pointer to the element that failed, so you can highlight the offending line instead of showing the user a paragraph of text.

Read extension → verdict for the headline without walking the issue list. It is one of:

Arabic

Send Accept-Language: ar and every message and suggestion comes back in Arabic. The rule codes do not change.

Checking at the point of care

Add "_mode": "clinical" at the top level of the payload when the check runs while a doctor is prescribing. It suppresses the structural and money rules — a prescription has no payer, no price and no filing deadline yet, and reporting those to a clinician trains them to ignore the warning.

Option B — upload a file

For systems that would rather not change their submission code, and for the initial audit of historical claims. Export one row per claim line, repeating the claim-level fields on each row.

curl -X POST https://icdsbs.com/api/v1/scrub/batch \
  -H "X-API-Key: sk_live_your_key_here" \
  -F "[email protected]" \
  -F "label=July claims"

Column names do not have to match anything — they are recognised by alias, including Arabic headers. These are understood:

The response gives you a batch id and the headline figures. Then:

Maximum upload 64 MB. Larger files should be split; a submit-and-collect mode for very large batches is on the roadmap.

The rules

Fetch the live catalogue — it is the authoritative list, in English and Arabic:

curl -H "X-API-Key: …" https://icdsbs.com/api/v1/scrub/rules

Severity:

error a payer edit catches this mechanically · warning commonly rejected, a coder should look · information worth knowing, not a defect

If a rule does not apply to your payers, tell us and we will switch it off for your account alone. Nothing is tuned globally to suit one customer.

Errors

Limits

What we store

Membership numbers are hashed the moment they arrive — enough to count the same member twice within one file, never enough to identify anyone. Identifying columns found in an uploaded file are read past and discarded, and the response tells you which ones were dropped.

Your data is visible only to your own account. Another customer asking for your batch by id receives "not found".

Go-live checklist