Convert Flat PDF to Fillable

Endpoint

POST /v1/forms/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/forms/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.

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).

---

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.
resolution	number	No	Inference resolution (imgsz). Default: 1600.

---

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/forms/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." }