Skip to content
Ditio Developer Docs

PDF Extraction

Pull the PDFs Ditio generates — checklist/form PDFs, alert (incident) PDFs, and absence PDFs — through the paginated data-extraction API. Each extraction record carries a pdfUrl download link to its rendered PDF, so you can sync documents incrementally into an archive or document management system without a dedicated per-document endpoint.

How it works

Section titled “How it works”

The rendered PDF is exposed as a field on the entity’s existing extraction record:

PDFExtraction endpointField
Checklist / formGET /v1/checklist-registrations, GET /v1/machine-checklist-registrationspdfUrl
Alert / incidentGET /v1/incident-registrations, GET /v1/machine-incident-registrationspdfUrl
AbsenceGET /v1/absence-registrationspdfUrl
  • Base (test): https://core-api.ditio.dev/reporting (production: https://core-api.ditio.app/reporting)
  • Auth: OAuth 2.0 client credentials, reportingapiv1 scope — see Authentication
  • All endpoints support the standard extraction filters: ProjectId, ModifiedSince / ModifiedBefore (incremental sync), ContinuationToken (paging) — see Pagination

pdfUrl is an absolute link to Ditio’s file endpoint, e.g. https://core-api.ditio.dev/core/api/file/{fileReferenceId}. It is null when no PDF has been generated for that record yet — generation happens when the checklist/alert/absence is submitted or reported, not on read. Skip records with a null pdfUrl and pick them up on a later sync.

Checklist records additionally expose files attached inside the checklist via sections[].attachments[].url and sections[].images[].url.

Fetching the PDF bytes

Section titled “Fetching the PDF bytes”

GET the pdfUrl with your bearer token:

Terminal window
curl -L -o alert.pdf \
  -H "Authorization: Bearer $TOKEN" \
  "https://core-api.ditio.dev/core/api/file/6610f1a3c5000000000000aa"

Example — incremental checklist + alert PDF sync

Section titled “Example — incremental checklist + alert PDF sync”
Terminal window
export DITIO_IDENTITY_BASE="https://identity.ditio.dev"          # test
export DITIO_REPORTING_BASE="https://core-api.ditio.dev/reporting"


# Reporting token (reportingapiv1 scope)
TOKEN=$(curl -s -X POST "$DITIO_IDENTITY_BASE/connect/token" \
  -d "client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET&grant_type=client_credentials&scope=reportingapiv1" \
  | jq -r '.access_token')


# Checklists changed since last sync — download each generated PDF
curl -s -G "$DITIO_REPORTING_BASE/v1/checklist-registrations" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "ProjectId=65a000000000000000000002" \
  --data-urlencode "ModifiedSince=2026-06-01T00:00:00Z" \
| jq -r '.data[] | select(.pdfUrl != null) | .pdfUrl' \
| while read -r url; do curl -sL -H "Authorization: Bearer $TOKEN" -O "$url"; done


# Same pattern for alerts
curl -s -G "$DITIO_REPORTING_BASE/v1/incident-registrations" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "ProjectId=65a000000000000000000002" \
  --data-urlencode "ModifiedSince=2026-06-01T00:00:00Z" \
| jq -r '.data[] | select(.pdfUrl != null) | .pdfUrl'

Follow continuationToken until it is empty to page through all results.

Python example

Section titled “Python example”
import os
import requests


REPORTING_BASE = os.environ.get(
    "DITIO_REPORTING_BASE", "https://core-api.ditio.dev/reporting"
)
headers = {"Authorization": f"Bearer {token}"}


params = {"ModifiedSince": "2026-06-01T00:00:00Z"}
while True:
    page = requests.get(
        f"{REPORTING_BASE}/v1/checklist-registrations",
        headers=headers, params=params,
    ).json()
    for record in page["data"]:
        pdf_url = record.get("pdfUrl")
        if pdf_url:  # None until the PDF has been generated
            pdf_bytes = requests.get(pdf_url, headers=headers).content
            archive(record["id"], pdf_bytes)  # your logic
    continuation = page.get("continuationToken")
    if not continuation:
        break
    params["ContinuationToken"] = continuation

Common issues

Section titled “Common issues”
IssueCauseFix
pdfUrl is nullPDF not generated yet — generation happens on submit/report, not on readSkip the record and pick it up on the next incremental sync
401 when fetching the PDF bytesThe file endpoint needs the same bearer tokenSend Authorization: Bearer on the pdfUrl request too
Old records never get a PDFThe record was never submitted/reported in DitioExpected — only submitted records produce PDFs
Section titled “Related”