Skip to main content

PDF/UA

Introduction​

Use this guide when you need accessible PDF output. PDF/UA (ISO 14289-1, "Universal Accessibility") is the technical basis for accessible tagged PDF: a PDF whose structure (headings, reading order, alternative text, tables, lists) is machine-readable so assistive technology can present it correctly. It is the PDF-side counterpart to the accessibility requirements that the European Accessibility Act references via EN 301 549 and WCAG 2.1 AA.

Prerequisites​

  • A PolyDoc account and API key — sign up for free, no credit card required. The free plan includes 150 PDF conversions per month.
  • A PDF conversion flow (HTML or URL source) whose source markup you control, so you can author it accessibly.

Configuration​

Enable PDF/UA output​

Set pdf.pdfua in your request payload to produce an accessible, tagged PDF that targets PDF/UA-1 (ISO 14289-1). Setting pdf.pdfua forces a tagged render automatically, so you do not need to enable tagging separately.
The value is an object. With { "verify": true }, PolyDoc validates the output against veraPDF's PDF/UA-1 profile and rejects non-compliant output instead of returning a PDF that fails (see below).
{
  "source": "<html lang=\"en\"><head><title>Invoice INV-2026-042</title></head><body><h1>Invoice INV-2026-042</h1></body></html>",
  "pdf": {
    "pdfua": {
      "verify": true
    }
  }
}

Verify compliance​

Set pdf.pdfua.verify to true to require PDF/UA-1 compliance: veraPDF runs after conversion against its PDF/UA-1 profile, and if the output is not compliant the API responds with 422 Unprocessable Entity (JSON body with code: "PDFUA_VERIFICATION_FAILED" and rule summaries). No PDF is returned in that case. When verification succeeds, you get a normal 200 response with the PDF body (same as without verify); machine-checkable compliance is implied by the absence of 422.
Omit verify or set it to false for a best-effort tagged render without a strict validation gate.
{
  "source": "<html lang=\"en\"><head><title>Archive copy</title></head><body><h1>Archive copy</h1></body></html>",
  "pdf": {
    "pdfua": {
      "verify": true
    }
  }
}

Author accessible HTML​

Most of what determines real accessibility lives in your source HTML. veraPDF can only check the structure it is given, so author the input so it can actually pass and so the parts a machine cannot check are correct too:
  • Use a semantic heading order, <h1> through <h6>, that matches the content hierarchy (no skipped levels, no headings used purely for styling).
  • Give every image an alt attribute. Use meaningful text for informative images and an empty alt="" for decorative ones.
  • Set a document <title> and a language with <html lang>.
  • Mark up tables properly: real <th> header cells with scope, not styled <td> cells.
  • Use real list elements (<ul>, <ol>, <li>) rather than manually bulleted paragraphs.
  • Ensure sufficient colour contrast between text and background.

Example request​

{
  "source": "<html lang=\"en\"><head><title>Invoice INV-2026-042</title></head><body><h1>Invoice INV-2026-042</h1></body></html>",
  "layout": {
    "format": "A4"
  },
  "pdf": {
    "pdfua": {
      "verify": true
    }
  }
}

Tips​