Skip to content
PDFlys

Accessibility API

Check a PDF

Analyze a PDF for accessibility compliance across WCAG 2.1 AA, Section 508, EN 301 549, and PDF/UA-1.

POST /api/v2/accessibility/check
Content-Type: multipart/form-data

Request

Parameter Type Required Description
file binary Yes The PDF file to check
standards string[] No Array of standards: wcag21aa, section508, en301549, pdfua1. Default: all
includeEvidence boolean No Include detailed evidence in response. Default: false

Example

curl -X POST https://api.pdflys.com/api/v2/accessibility/check \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@annual-report.pdf" \
  -F 'standards=["wcag21aa","pdfua1"]'

Response (Synchronous — files under 50 MB)

{
  "success": true,
  "data": {
    "report": {
      "score": 72,
      "band": { "grade": "B", "label": "Good" },
      "totalChecks": 30,
      "passed": 22,
      "failed": 6,
      "warnings": 2,
      "categories": [
        {
          "name": "structure",
          "passed": 3,
          "failed": 1,
          "checks": [
            {
              "checkId": "1.1",
              "name": "Document is tagged",
              "status": "pass",
              "severity": "critical",
              "certainty": "verified",
              "evidence": []
            }
          ]
        }
      ],
      "violations": []
    },
    "standards": {
      "wcag21aa": {
        "conformance": "partial",
        "passed": 28,
        "failed": 4,
        "notApplicable": 62
      },
      "pdfua1": {
        "conformance": "fail",
        "passed": 12,
        "failed": 3,
        "notApplicable": 5
      }
    },
    "reportId": 42
  }
}

Note

The reportId field is only present for authenticated requests. Use it to retrieve the report later via the Reports API.

Response (Asynchronous — files over 50 MB)

Files over 50 MB require authentication and are processed asynchronously:

{
  "success": true,
  "data": {
    "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "queued"
  }
}

HTTP status: 202 Accepted

Poll Job Status

Check the progress of an asynchronous accessibility check job.

GET /api/v2/accessibility/check/status/:jobId

Auth required: Yes

Response

{
  "success": true,
  "data": {
    "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "completed",
    "progress": 100,
    "reportId": 42,
    "errorMessage": null,
    "createdAt": "2026-02-25T10:00:00.000Z",
    "completedAt": "2026-02-25T10:01:30.000Z"
  }
}

Status values:

Status Description
queued Job accepted, waiting to start
processing Engine is analyzing the PDF
completed Check finished — reportId field contains the report ID
failed Job failed — errorMessage field contains details

Tip

Poll every 2–5 seconds. Jobs typically complete within 30–120 seconds depending on document size.

Fix a PDF

Apply automated Tier 1 fixes to a PDF. Tier 1 fixes run server-side and cover structural and metadata issues.

POST /api/v2/accessibility/fix
Content-Type: multipart/form-data

Auth required: Yes

Request

Parameter Type Required Description
file binary Yes The PDF file to fix
checkIds string[] No Array of check IDs to fix. Default: all applicable Tier 1 checks
decorativePages number[] No 0-based page indices to mark as decorative
languageOverride string No Override document language (e.g., en, fr). 2–16 chars
titleOverride string No Override document title. 1–512 chars

Supported Check IDs (Tier 1)

Check ID Fix Description
1.3 Set document title
1.4 Set document language
1.5 Mark as tagged PDF
1.8 Set tab order
1.9 Set display document title
3.3 Mark decorative images
6.3 Fix metadata

Example

curl -X POST https://api.pdflys.com/api/v2/accessibility/fix \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf" \
  -F 'checkIds=["1.3", "1.4", "1.5"]' \
  -F "titleOverride=Annual Report 2026" \
  -F "languageOverride=en"

Response

{
  "success": true,
  "data": {
    "fixedPdfUrl": "https://storage.pdflys.com/a11y-fixed/abc123.pdf?token=...",
    "manifest": {
      "manifestVersion": "1.0.0",
      "originalHash": "sha256:abc...",
      "fixedHash": "sha256:def...",
      "entries": [
        {
          "checkId": "1.3",
          "operation": "setTitle",
          "applied": true,
          "detail": "Set document title to 'Annual Report 2026'"
        }
      ]
    },
    "results": [...],
    "beforeAfter": {
      "before": { "score": 62, "grade": "C" },
      "after": { "score": 78, "grade": "B" },
      "improved": true
    }
  }
}

If no fixes were applicable, fixedPdfUrl will be null and beforeAfter.improved will be false.

Anonymous vs Authenticated

Feature Anonymous Authenticated
Accessibility check Yes Yes
Report persistence No Yes (reportId returned)
Async processing (>50 MB) No Yes
Fix endpoint No Yes
Rate limit Stricter Tier-based