Convert Flat PDF to Fillable

Endpoint

POST /v1/utils/convert

Description

Starts an asynchronous flat -> fillable PDF conversion using Instafill's Python processing engine. Accepts raw PDF bytes or multipart/form-data, forwards the file to the converter, and returns a job_id you can poll with GET /v1/utils/convert/{job_id}/status.

Supported parameters:

• pages — convert only specific pages (e.g., "1,3-5").
• confidence — detection confidence threshold (conf). Default: 0.1.
• resolution — image resolution (imgsz) for inference. Default: 1600.
• allowCheckboxes — whether a box that looks like a checkbox becomes one. Default: true.
• autoConfirm — mark the form reviewed as soon as it converts. Default: false.
• stampConfidence — diagnostic: draw each field's confidence on the page. Default: false.

This endpoint does not return the final PDF — only a job_id.

---

File name handling

Two ways to set the original file name (used for storage):

1. Send multipart/form-data — the uploaded file name is used.
2. Send raw bytes (application/pdf or application/octet-stream) and pass header X-File-Name.

If neither a multipart filename nor X-File-Name is provided, the server generates {Guid}_{unix_timestamp}.pdf.

---

Request

Headers

Header	Required	Value
Content-Type	Yes	application/pdf, application/octet-stream, or multipart/form-data
X-File-Name	No	Optional original file name (used when not sending multipart).
X-Use-Cache	No	Reuse detections already computed for an identical page. Default: true. Set false to make the detector look again.

---

Query Parameters

Name	Type	Required	Description
pages	string	No	Pages to convert ("1", "1,3", "1-5", "1,3-5").
confidence	number	No	Detection confidence (conf). Default: 0.1. Lower finds more real fields and more false ones.
resolution	number	No	Inference resolution (imgsz). Default: 1600. Accepted from 1 to 3008.
allowCheckboxes	boolean	No	Default: true. When false, everything detected becomes a text field, including boxes that look like checkboxes.
autoConfirm	boolean	No	Default: false. When true, the form is marked reviewed as soon as it converts, instead of waiting for a person to check it.
stampConfidence	boolean	No	Default: false. Diagnostic — see below.

---

Stamping confidence on the page

stampConfidence=true draws each detected field's confidence score above the field it belongs to, in small red type. It answers by eye which fields a confidence threshold is about to lose, over a whole form, which is otherwise a matter of converting the document twice and comparing the two PDFs field by field.

The scores are page content, not annotations, so they cannot be switched off or removed afterwards. The form that comes back is readable and fillable but is not something to hand on. Use it to pick a confidence value, then convert again without the flag.

A field the detector did not score is left unmarked.

curl -X POST "https://api.instafill.ai/v1/utils/convert?confidence=0.1&stampConfidence=true" \
     -H "x-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/pdf" \
     --data-binary "@flat-form.pdf"

---

Body

Either:

1. Raw bytes of the PDF file
   • Content-Type: application/pdf or application/octet-stream
   • Optionally provide X-File-Name header

or

2. Multipart form with a file field
   • Content-Type: multipart/form-data
   • Backend uses the uploaded file name.

---

cURL Example

curl -X POST "https://api.instafill.ai/v1/utils/convert?pages=1,3-5&confidence=0.25&resolution=1900" \
     -H "x-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/pdf" \
     --data-binary "@flat-form.pdf"

Response Body:

{
  "job_id": "675f5d197d9800b68b5c4c44"
}

---

Responses

• 200 OK — JSON from the converter, typically { "job_id": "<id>" }.
• 415 Unsupported Content Type — when Content-Type is not application/pdf, application/octet-stream, or multipart/form-data.

  { "error_message": "Expected octet-stream or pdf or multipart/form-data" }
• Non-200 from the converter — the same status code is forwarded with

  { "error_message": "Error when starting conversion." }