Convert PDFs to PDF/UA-1

Document Engine can automatically tag PDF files and target PDF/UA-1 output by using build instructions with output.type set to pdfua.

• Ensure Document Engine is up and running.
• Send a multipart POST request(opens in a new tab) with instructions to Document Engine’s /api/build endpoint.

For more information, refer to the API reference to learn about the /api/build endpoint and all the actions you can perform on PDFs with Document Engine.

For an overview of multipart requests, refer to the brief tour of multipart requests blog post.

Convert a PDF file to PDF/UA-1

Send a multipart request to the /api/build endpoint, attaching the input PDF and the instructions JSON.

curl -X POST http://localhost:5001/api/build \
  -H "Authorization: Token token=<API token>" \
  -F document=@/path/to/input.pdf \
  -F instructions='{
  "parts": [
    {
      "file": "document"
    }
  ],
  "output": {
    "type": "pdfua",
    "metadata": {
      "title": "Accessible annual report",
      "author": "Nutrient"
    }
  }
}' \
  -o output-pdfua.pdf

POST /api/build HTTP/1.1
Content-Type: multipart/form-data; boundary=customboundary
Authorization: Token token=<API token>

--customboundary
Content-Disposition: form-data; name="document"; filename="input.pdf"
Content-Type: application/pdf

<PDF data>
--customboundary
Content-Disposition: form-data; name="instructions"
Content-Type: application/json

{
  "parts": [
    {
      "file": "document"
    }
  ],
  "output": {
    "type": "pdfua",
    "metadata": {
      "title": "Accessible annual report",
      "author": "Nutrient"
    }
  }
}
--customboundary--

Apply PDF/UA auto-tagging to an existing Document Engine document

If your document is already stored in Document Engine, use /api/documents/{documentId}/apply_instructions.

This replaces the document’s base layer with the processed (tagged) result:

curl -X POST "http://localhost:5001/api/documents/<documentId>/apply_instructions" \
  -H "Authorization: Token token=<API token>" \
  -H "Content-Type: application/json" \
  -d '{
  "parts": [
    {
      "document": {
        "id": "#self"
      }
    }
  ],
  "output": {
    "type": "pdfua"
  }
}'

Direct Word-to-PDF/UA conversion

In Document Engine 1.19.0 and later, the Build API can convert a Word document to PDF/UA in a single processing step. Document Engine takes this path when the Word document is the only build part and the pdfua output requests no other PDF processing.

This path preserves the structure from the Word document instead of reconstructing tags from an intermediate PDF. Builds with multiple parts, actions, page ranges, or additional output options continue to convert the assembled PDF to PDF/UA.

Validate PDF/UA-1 conformance

Document Engine 1.18 and later can validate PDF/UA-1 conformance with the POST /api/validate_pdfua endpoint. Use it in QA workflows after auto-tagging, or to check an existing PDF before distribution:

curl -X POST http://localhost:5001/api/validate_pdfua \
  -H "Authorization: Token token=<API token>" \
  -F document=@/path/to/output-pdfua.pdf

The endpoint accepts uploaded PDFs, remote URLs, and existing Document Engine documents, and it returns a machine-readable validation report.

Notes and best practices

• pdfua output returns a PDF file (application/pdf).
• Auto-tagging reduces manual accessibility work but doesn’t replace validation. High-stakes, regulated, and strict-compliance workflows should check the output in a quality assurance (QA) process.
• You can combine pdfua with other base PDF output model options, such as metadata and optimization.
• Some optional output settings may require additional licensed features in your Document Engine deployment.