Upload Form

Endpoint

POST /v1/forms/upload

Description

Uploads a single PDF form file and triggers Instafill's batch-processing pipeline.
The file is first stored in Instafill's template blob storage, then forwarded to the downstream /forms/batch service.
The response is an array (length = 1) containing the parsed form's metadata and detected fields.

Accepted file types — application/pdf or application/octet-stream
Any other Content-Type returns 415 Unsupported Content Type.

---

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 or application/octet-stream
Authorization	Yes	Bearer YOUR_API_KEY
X-File-Name	No	Optional original file name (used when not sending multipart).

Body

Binary contents of the PDF file.

curl -X POST https://api.instafill.ai/v1/forms/upload \
     -H "x-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/pdf" \
     --data-binary "@sample-form.pdf"

Responses

Success — 200 OK

Returns an array with the result of the form upload and processing:

{
    "id": "uf_50a7cd169edd47a093168a29792733cd",
    "object": "upload_form",
    "form_id": "6866495ea5c8a5bac52a3c7f",
    "file_name": "6d4a5144-3725-48be-b7ae-4318c271e87a_1751533840.pdf"
}

Error — 415 Unsupported Content Type

Returned when the request's Content-Type is not application/pdf or application/octet-stream.

{
  "id": "error_6b63acaf4baf4d179b33ebe580571c0a",
  "created": "2024-06-19T13:45:08.4531108Z",
  "object": "error",
  "error_message": "Expected octet-stream or pdf"
}