Understanding the score

Every completed case carries a score — a single integer from 0 to 100 that rates the accessibility quality of the remediated PDF/UA result. You read it from GET /job-status/{caseId}:

{ "jobStatus": "completed", "stage": "finished", "score": 87 }

Higher is better: 100 means no accessibility problems remained after remediation.

When the score is final

The number is only meaningful once the job is completed (stage: finished). Before that it is a placeholder — a queued case reports "score": 0, and during revalidating the score is still being recomputed against the remediated file. Read it only after the terminal completed status; ignore it for every other state.

Note

The score describes the result we produce, not your upload. It measures what is still wrong after Accessful has fixed everything it could — so it answers “how accessible is the file I’m about to download”, not “how bad was the original”.

How it’s calculated

The score is penalty-based. Every file starts at 100, and each accessibility problem that remains in the result subtracts from it. Four things shape the number:

• Severity dominates. A structural blocker costs far more than a cosmetic finding. Severities, heaviest first:

  Severity	What it covers
  Blocker	Core tag structure, untagged images, missing document language
  Major	Significant structural problems for assistive technology
  Minor	Metadata, bookmarks, page numbering, artifacts
  Info	Best-practice / informational findings

• Fixed costs nothing. Only open findings count. Everything Accessful successfully remediated is free — that is the whole point of the conversion.

• Repeats don’t dominate. Many findings of the same type are dampened logarithmically, so the same issue across 200 pages is not penalised 200× more than it would be on one page.

• Manual review is cheap. A few issues can’t be auto-fixed with confidence (e.g. “is this alt text actually meaningful?”). Those carry a small flat penalty instead of the full severity weight and are left for a human to confirm.

A quality signal, not a legal certificate

A high score means few accessibility problems remain — it is not a guarantee of legal PDF/UA conformance and not a substitute for a manual accessibility audit. Treat it as a strong indicator, not a compliance sign-off.

The exact weighting is tuned over time as remediation quality improves; only the 0–100 range and “higher is better” are part of the API contract.

Reading a score

The API returns only the number. As a practical rule of thumb:

Score	Read it as	Typical action
90–100	Excellent — essentially clean	Ship it.
75–89	Good — minor issues remain	Usable as-is; spot-check high-stakes documents.
50–74	Fair — real gaps remain	Review before publishing; the source likely had structural weaknesses.
Below 50	Poor	The source was hard to remediate automatically; improve it and re-upload.

Why a score isn’t higher

The most common reason a score plateaus below 100 is the source document: a scanned PDF with no text layer, images that can’t be described with confidence, or content whose reading order can’t be inferred safely. Accessful fixes structure, tags, metadata, language and alt text wherever it can determine them reliably, and leaves the rest as open or manual-review findings rather than guessing.

To move the number, improve the source — add a real text layer, supply genuine headings — and upload the new file. Re-submitting the same bytes won’t help: identical content is detected as a duplicate and skipped.