PDF accessibility API: check and tag PDFs automatically

Why a PDF/UA API?

Accessibility rarely fails for lack of knowledge. It fails because of volume. Invoices, official notices, reports and forms are produced automatically, often by systems that cannot create tagged PDFs. A check-and-tag interface lets you inspect every document inside the process, before it reaches customers or citizens.

Typical use cases:

• Document management: check new documents on import and store the findings as metadata.
• Invoices and official notices: check generated PDFs before sending and add baseline tags.
• CMS upload checks: editors get immediate feedback on upload if title, language or tags are missing.
• Batch migration: scan existing document archives systematically and prioritise which files need rework.

Endpoints at a glance

The REST API has three endpoints. All of them require a personal bearer token in the Authorization header.

• POST /api/v1/inspect/: checks a PDF sent as the multipart field pdf. The document is not modified.
• POST /api/v1/tag/: creates a retroactively tagged copy. Along with pdf, you send title and language (a BCP 47 code such as en-GB).
• GET /api/v1/download/?token=…: downloads the tagging result, using the same bearer header.

Example: check a PDF

curl -X POST https://easypdfua.com/api/v1/inspect/ \
  -H "Authorization: Bearer $EASYPDFUA_TOKEN" \
  -F "pdf=@report.pdf"

The JSON response has three parts: status (success, operation, API version, timestamp), result with the assessment (pdfUaOk, verdict, warningCount) and details with the full report, including the structure tree and warnings.

Example: tag and download a PDF

curl -X POST https://easypdfua.com/api/v1/tag/ \
  -H "Authorization: Bearer $EASYPDFUA_TOKEN" \
  -F "pdf=@report.pdf" \
  -F "title=Annual Report 2026" \
  -F "language=en-GB"

# Response (shortened)
{
  "status": { "success": true, "operation": "tag", ... },
  "result": {
    "verdict": "issues_found",
    "outcome": "tagged",
    "output": {
      "downloadUrl": "https://easypdfua.com/api/v1/download/?token=…",
      "sha256": "…",
      "expiresInSeconds": 900,
      "singleUse": true
    }
  },
  "details": { ... }
}

curl -H "Authorization: Bearer $EASYPDFUA_TOKEN" \
  -o report-tagged.pdf "<downloadUrl>"

The download URL is valid for 15 minutes and can be retrieved exactly once. If a PDF is already tagged, it is only analysed (outcome: already-tagged-analyzed) and no new file is created. Use the SHA-256 hash in the response to verify the download.

Security and privacy

• The token is shown in full only once. Only its SHA-256 hash is stored.
• PDF contents are not sent to external services and are not stored in logs.
• The same conservative safety rules apply as in the browser: encrypted, signed or technically ambiguous PDFs are rejected rather than modified at risk.
• Errors are returned as JSON with error.code and a matching HTTP status, for example 401 for an invalid token or 413 for files that are too large.

What tagging does, and what it does not

Automatic tagging is deliberately conservative. It adds a structure tree with a Document element and one paragraph (P) per page, anchors links as Link tags, sets the title, document language, the PDF/UA identifier in the XMP metadata and the tab order, and, where this is unambiguous, repairs missing Unicode mappings (ToUnicode).

The API does not create semantic structures such as headings, tables, lists or alternative text for images. Those require an understanding of the content and usually manual editing. Read more in Tag an existing PDF.

For automated quality assurance we recommend validating results with veraPDF as well. The open-source validator fits well into CI pipelines and batch jobs. Its typical messages are explained in Common PAC and veraPDF errors.

Getting API access

The API is part of the Premium plan: files up to 50 MB, unlimited operations and a personal token that you create under “API access” in the application. See Premium.

Frequently asked questions

Who can use the API?

The API is available to Premium accounts only. Free accounts can see the API section but cannot create a token.

How large can PDFs be?

Premium accounts can process PDFs up to 50 MB per file through the API, with no daily limit on operations.

How long is the tagged PDF available?

The download URL is valid for 15 minutes and can be retrieved only once. The file is deleted afterwards.

Is the API result a PDF/UA certification?

No. The assessment is based on EasyPDFUA’s internal checks and is not a normative PDF/UA validation. Cross-checking with veraPDF or PAC and a manual review remain recommended.