Skip to main content

API Overview

Use this page to understand what the Bulk Fill Public API is, why it behaves the way it does, and how it fits with the Doqlo web editor.

What The Public API Is​

The Bulk Fill Public API is an execution API. You prepare the layout and field mapping in the web Bulk Fill editor, export a .doqlo package, then submit that package to the API with a source PDF, row data, and execution options.

The API is not a second authoring surface. It does not accept field placements or mapping definitions directly, and it does not replace the editor workflow that creates the package you execute.

What .doqlo Is For​

.doqlo is the reusable configuration package exported from the Bulk Fill web editor. It carries the layout, field mapping, and execution configuration that the API runs against your incoming data.

For public execution, .doqlo is:

  • a sealed Doqlo-produced package
  • reusable across similar PDFs where the same placements still make sense
  • not a raw editor-state dump
  • not a promise that one exact PDF fingerprint is the only valid input

Why The API Is Flexible​

Real-world document operations are rarely perfectly uniform. A PDF may keep the same practical layout while changing minor metadata, pagination details, or other compatible structure.

Doqlo is designed to stay useful in those cases:

  • package and input validation stay strict
  • accepted jobs execute best-effort
  • some placements may be skipped instead of failing the whole job
  • rows can succeed, partially succeed, or fail independently
  • manifest.json explains what happened

Static QR/barcode overlays are a narrow defensive exception on the public API: if an uploaded package still contains empty, invalid, or malformed static code overlay data, those overlays are skipped and reported in manifest.json instead of failing the accepted job.

That flexibility is a product feature. It exists to help teams keep producing usable output while staying explicit about partial results.

Read Reuse .doqlo Project Files Across PDFs for the product rationale and practical examples behind this flexibility.

Threshold And Billing At A Glance​

Every request must include max_failed_row_percent. That number is not a hidden default or a low-level tuning flag. It is your explicit acceptance boundary for failed rows.

Two rules matter most:

  • if the job stays within your declared threshold, it completes and uses normal input-row quota semantics
  • if the job exceeds your declared threshold, it fails, no output is delivered, and it does not consume quota

That means threshold control does not turn the API into a pay-only-for-produced-files model. It lets you decide when partial loss is acceptable.

How Results Stay Transparent​

Completed jobs download a ZIP artifact that contains:

  • one produced row PDF for each success or partial row
  • manifest.json with top-level diagnostics, row-level status, warning details, and aggregate counts

If a job fails because it exceeded your threshold, there is no ZIP artifact. Instead, the failed job response and any failed webhook surface the threshold diagnostics directly.

When To Use The API Versus The Web App​

Use the Public API when:

  • another system needs to trigger exports
  • you want server-to-server delivery
  • you need polling or webhook-based job handling
  • you want to reuse editor-authored packages in operational workflows

Use the Bulk Fill web app when:

  • a person is placing fields and previewing rows visually
  • you want to iterate on the layout before automating it
  • you only need occasional manual exports

High-Level Flow​

  1. Create the layout in the web Bulk Fill editor.
  2. Export the .doqlo package from that editor workflow.
  3. Submit the package, the source PDF, row data, and your threshold.
  4. Poll the job or wait for a webhook.
  5. Download the ZIP and inspect manifest.json, or inspect failed-job diagnostics if the threshold was exceeded.