create-session

id: create-session title: Create Session sidebar_position: 3

Create Session

Endpoint

POST /v1/session

Description

Creates a new autofill session for a specified PDF form.
The endpoint can respond in two ways depending on the Accept header you send:

`Accept` header you send	Response type	When to use it
`application/pdf` (or `application/json, application/pdf`)	A fully‑filled PDF binary (`Content-Type: application/pdf`)	When you want a single synchronous call that immediately returns the ready‑to‑download form.
`application/json` (default)	A JSON payload containing the session ID and status	When you prefer an asynchronous flow—create the session, then poll `GET /v1/session/{id}` until the status is `completed`, then download the PDF.

Tip: In synchronous mode the server streams the PDF. Save the response body to disk (see code snippet in the quick‑start guide).

Request

Headers

Name	Value	Required
`Content-Type`	`application/json`	✓
`x-api-key`	Your Instafill.ai API key	✓
`Accept`	`application/pdf` or `application/json`	Optional – controls sync vs async

Body

{
  "form_id": "6840582d3745268a298e0283",
  "sources": [
    "name: Kirill Biliashov"
  ],
  "instructions": "Optional extra instructions"
}

Field	Type	Description
`form_id`	`string`	Unique identifier of the form template.
`sources`	`string[]`	Array of input strings. Each item can be plain text (e.g., `"name: Jane Doe"`) or a public URL pointing to a file containing data (TXT, PDF, image, etc.).
`instructions`	`string`	(Optional) Extra instructions to fine‑tune how Instafill.ai fills the form.

Success Responses

1. Synchronous – PDF returned directly

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="w9-2024_filled.pdf"

Binary body contains the filled PDF. Save it as desired (e.g., instafill.pdf).

2. Asynchronous – JSON session envelope

{
  "id": "cs_44cfe04df1114b6c81326fe61951b81d",
  "created": "2025-06-20T10:17:22.848106Z",
  "object": "session",
  "session_id": "66700d319ad27d71fa6cbd8d",
  "status": "queued"
}

Poll GET /v1/session/{session_id} until you receive:

{
  "status": "completed",
  "filled_form_url": "https://instafill-files.s3.amazonaws.com/..."
}

Then download the PDF from filled_form_url.

Error Response

{
  "id": "error_7d7f52761e134352addbd1b406a15ba0",
  "created": "2025-06-20T13:41:47.499164Z",
  "object": "error",
  "error_message": "Unable to create session."
}

Common causes include an invalid form_id, malformed JSON, or authentication failure.

id: create-session title: Create Session sidebar_position: 3​

Create Session

Endpoint​

Description​

Request​

Headers​

Body​

Success Responses​

1. Synchronous – PDF returned directly​

2. Asynchronous – JSON session envelope​

Error Response​