> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runpulse.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Fill Form
> Fill the fields of a PDF form with values inferred from a natural
language `instructions` prompt. Works on both AcroForm PDFs
(true form fields are written) and flat/scanned PDFs (values
are rendered as an overlay using detected cells from OCR).
**Input modes** — provide exactly one of:
- `form_id` — reuse a previously processed form from a prior
`/form/detect`, `/form/fill`, or `/form/clear` call. Skips
re-detection (fast path); the cached `form_fields` are
reused.
- `file_url` — public or pre-signed URL of a PDF Pulse will
download.
- `file` — direct binary upload of the PDF. Pulse runs cell
detection internally before filling.
All three input modes ride on the same `multipart/form-data`
request body. (Callers sending `Content-Type: application/json`
with `form_id` / `file_url` are still accepted server-side for
backward compatibility, but the SDKs only model the multipart
form.)
Optional `form_fields` lets callers supply or edit the detected
cells before filling. Optional `page_range` (alias `pages`,
e.g. `"1-3,5"`) restricts the operation to a subset of pages.
Synchronous by default — returns the filled `FormResult` inline
(including a `pdf_url` you can `GET` to download the PDF
binary). Set `async: true` to receive `{job_id, status:
"pending"}` and poll [GET /job/{jobId}](api:GET/job/{jobId}).
Billed at **3 credits per page**. Requires the `form_filler`
feature flag to be enabled for your organization.
## Overview
Fill a PDF form from natural-language instructions. Returns a `FormResult` synchronously by default (with a `pdf_url` you can `GET` to download the filled PDF). Set `async: true` to run in the background and poll [GET /job{'{'}jobId{'}'}](/api-reference/endpoint/poll) for the result.
`/form/fill` writes values into the fields of a PDF form based on a natural-language `instructions` prompt. It works on both PDFs with native form fields (where the values are written directly into the form) and on flat or scanned PDFs (where the values are placed into the detected fields).
### Providing the PDF
Provide the PDF in **exactly one** of the following ways:
* `form_id`: chain off a prior [`/form/detect`](/api-reference/endpoint/form-detect), `/form/fill`, or [`/form/clear`](/api-reference/endpoint/form-clear) call. The cached PDF and `form_fields` are reused, so there is no need to re-upload.
* `file_url`: public or presigned URL to a PDF.
* `file`: PDF uploaded inline with the request.
Sending more than one (or none) returns `400`.
All three input modes ride on the same `multipart/form-data` request body — that's how the SDKs send every call. JSON bodies (`Content-Type: application/json`) with `form_id` or `file_url` are still accepted server-side for backward compatibility, but the SDKs only model the multipart form.
### Pricing
Billed at **3 credits per page** of the PDF being filled. Every response also returns a top-level `credits_used` for **this request** and a cumulative `plan_info.total_credits_used` snapshot for your organization.
***
## Request
### Request Body
| Field | Type | Required | Description |
| -------------- | ------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| `form_id` | string (uuid) | One of these | Reuse a previously processed form. Skips re-upload and re-detection. |
| `file_url` | string (uri) | One of these | Public or presigned URL of a PDF to download and fill. |
| `file` | binary | One of these | PDF uploaded inline with the request. |
| `instructions` | string | Yes | Natural-language description of what to fill into the form. Example: `"Use John Doe, 123 Main St, born 1990-01-01"`. |
| `form_fields` | array of [`FormCell`](#response.body.form_fields) | No | Optional override for the cells used when filling. Useful when the caller has hand-edited the cells returned by `/form/detect`. |
| `page_range` | string | No | 1-based page filter, for example `"1,3-5"`. Alias `pages` accepted. |
| `async` | boolean | No | When `true`, returns `{ job_id, status: "pending" }` immediately (HTTP 202) and processes the job in the background. Default `false`. |
***
## Response
### Sync (200): `FormResult`
When `async` is `false` (default), the call returns a `FormResult` body directly.
| Field | Type | Description |
| --------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `form_id` | string (uuid) | ID of the new form record produced by this run. Pass back via `form_id` to chain further fills, clears, or detects. |
| `page_count` | integer | Number of pages in the output PDF. |
| `pdf_url` | string (uri) | URL to download the filled PDF binary. Always points at [GET /results/{'{'}jobId{'}'}/pdf](/api-reference/endpoint/poll). Requires the same auth (API key or JWT) as the rest of the API and only serves results owned by the calling organization. |
| `form_fields` | array of [`FormCell`](#response.body.form_fields) | Detected cells of the resulting (filled) PDF, refreshed after the fill. |
| `fields_filled` | integer | Number of cells whose value actually changed during this run (no-op writes are not counted). |
| `credits_used` | number | Credits consumed by this request (`3 × page_count`). |
| `plan_info` | object | `{ tier, total_credits_used, pages_used }` cumulative billing snapshot for your organization (post-request). |
```json theme={null}
{
"form_id": "00e2c454-4e6f-429b-bd74-320ad94b2153",
"page_count": 6,
"pdf_url": "https://api.runpulse.com/results/dab7285d-8a65-4cb6-9d24-d5db64d3798e/pdf",
"form_fields": [
{
"page_number": 1,
"type": "text",
"bounding_box": [0.118, 0.226, 0.634, 0.241],
"text": "Acme Logistics LLC"
},
{
"page_number": 1,
"type": "checkbox",
"bounding_box": [0.118, 0.226, 0.634, 0.241],
"text": "Individual/sole proprietor C corporation S corporation Partnership",
"checkbox_details": [
{ "center_coord": [0.125, 0.232], "selected": true, "text": "Individual/sole proprietor" },
{ "center_coord": [0.300, 0.232], "selected": false, "text": "C corporation" },
{ "center_coord": [0.418, 0.232], "selected": false, "text": "S corporation" },
{ "center_coord": [0.535, 0.232], "selected": false, "text": "Partnership" }
]
}
],
"fields_filled": 7,
"credits_used": 18.0,
"plan_info": {
"tier": "pulse_ultra_2",
"total_credits_used": 1284.0,
"pages_used": 428
}
}
```
All cell coordinates (`bounding_box`, `checkbox_details[].center_coord`) are normalized to `[0, 1]` with a top-left origin. Multiply by your render width / height to convert to pixel coordinates.
### Async (202): `FormJobAccepted`
When `async` is `true`:
```json theme={null}
{
"job_id": "abc123-def456-ghi789",
"status": "pending"
}
```
Poll [GET /job/{'{'}jobId{'}'}](/api-reference/endpoint/poll). The job's `result` carries the same `FormResult` shape that the sync flow would have returned inline.
### Status Codes
| Code | Description |
| ---- | --------------------------------------------------------------------------------------------------- |
| 200 | Filled `FormResult` returned synchronously. |
| 202 | Async job accepted (`async: true`). Poll `/job/{jobId}` for the result. |
| 400 | Missing PDF, more than one PDF source provided, missing `instructions`, or malformed `form_fields`. |
| 401 | Authentication failed or missing API key. |
| 404 | Referenced `form_id` not found (or belongs to a different org). |
| 500 | Internal server error. |
***
## Example Usage
### Fill From URL
```python Python theme={null}
from pulse import Pulse
client = Pulse(api_key="YOUR_API_KEY")
result = client.form.fill(
file_url="https://example.com/intake-form.pdf",
instructions="Fill in patient name as Jane Doe, DOB 01/15/1990.",
)
print(f"form_id={result.form_id}")
print(f"fields_filled={result.fields_filled}")
print(f"credits_used={result.credits_used}")
print(f"download: {result.pdf_url}")
```
```typescript TypeScript theme={null}
import { PulseClient } from "pulse-ts-sdk";
const client = new PulseClient({ apiKey: "YOUR_API_KEY" });
const result = await client.form.fill({
file_url: "https://example.com/intake-form.pdf",
instructions: "Fill in patient name as Jane Doe, DOB 01/15/1990.",
});
console.log(`form_id=${result.form_id}`);
console.log(`fields_filled=${result.fields_filled}`);
console.log(`download: ${result.pdf_url}`);
```
```bash curl theme={null}
curl -X POST https://api.runpulse.com/form/fill \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"file_url": "https://example.com/intake-form.pdf",
"instructions": "Fill in patient name as Jane Doe, DOB 01/15/1990."
}'
```
### File Upload
```python Python theme={null}
with open("intake-form.pdf", "rb") as f:
result = client.form.fill(
file=f,
instructions="Fill in patient name as Jane Doe, DOB 01/15/1990.",
)
```
```typescript TypeScript theme={null}
import * as fs from "fs";
const fileBuffer = fs.readFileSync("intake-form.pdf");
const blob = new Blob([fileBuffer], { type: "application/pdf" });
const result = await client.form.fill({
file: blob,
instructions: "Fill in patient name as Jane Doe, DOB 01/15/1990.",
});
```
```bash curl theme={null}
curl -X POST https://api.runpulse.com/form/fill \
-H "x-api-key: YOUR_API_KEY" \
-F "file=@intake-form.pdf" \
-F "instructions=Fill in patient name as Jane Doe, DOB 01/15/1990."
```
### Detect First, Then Fill
Run [`/form/detect`](/api-reference/endpoint/form-detect) to inspect the detected cells, optionally edit them, then chain a fill that reuses the same `form_id`. There is no need to re-upload the PDF.
```python Python theme={null}
detect = client.form.detect(file_url="https://example.com/intake-form.pdf")
# (Optional) edit detected cells locally, e.g. retype a misclassified cell
edited = []
for cell in detect.form_fields or []:
if cell.text and cell.text.strip().lower() == "signature":
cell.type = "signature"
edited.append(cell)
result = client.form.fill(
form_id=detect.form_id,
instructions="Fill in patient name as Jane Doe, DOB 01/15/1990.",
form_fields=edited, # omit to use the cached cells from detect
)
```
```typescript TypeScript theme={null}
const detect = await client.form.detect({
file_url: "https://example.com/intake-form.pdf",
});
const edited = (detect.form_fields ?? []).map((cell) =>
cell.text?.trim().toLowerCase() === "signature"
? { ...cell, type: "signature" as const }
: cell,
);
const result = await client.form.fill({
form_id: detect.form_id!,
instructions: "Fill in patient name as Jane Doe, DOB 01/15/1990.",
form_fields: edited,
});
```
```bash curl theme={null}
# Step 1: detect
curl -X POST https://api.runpulse.com/form/detect \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"file_url": "https://example.com/intake-form.pdf"}'
# Step 2: fill via the form_id from step 1
curl -X POST https://api.runpulse.com/form/fill \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"form_id": "",
"instructions": "Fill in patient name as Jane Doe, DOB 01/15/1990."
}'
```
### Async Fill With Polling
Use `async: true` for long-running jobs (large PDFs, multi-page fills) so the client does not have to keep a connection open.
```python Python theme={null}
import time
submission = client.form.fill(
file_url="https://example.com/big-form.pdf",
instructions="Fill the form for Jane Doe ...",
async_=True, # SDK aliases the reserved keyword
)
while True:
job = client.jobs.get_job(job_id=submission.job_id)
if job.status in ("completed", "failed"):
break
time.sleep(2)
result = job.result # same FormResult body as the sync flow
print(f"fields_filled={result['fields_filled']} pdf_url={result['pdf_url']}")
```
```typescript TypeScript theme={null}
const submission = await client.form.fill({
file_url: "https://example.com/big-form.pdf",
instructions: "Fill the form for Jane Doe ...",
async: true,
});
let job = await client.jobs.getJob({ jobId: submission.job_id! });
while (job.status !== "completed" && job.status !== "failed") {
await new Promise((r) => setTimeout(r, 2000));
job = await client.jobs.getJob({ jobId: submission.job_id! });
}
const result = job.result as Record;
console.log(`fields_filled=${result.fields_filled} pdf_url=${result.pdf_url}`);
```
```bash curl theme={null}
# Submit async
curl -X POST https://api.runpulse.com/form/fill \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"file_url": "https://example.com/big-form.pdf",
"instructions": "Fill the form for Jane Doe ...",
"async": true
}'
# Poll
curl https://api.runpulse.com/job/ \
-H "x-api-key: YOUR_API_KEY"
```
### Download The Filled PDF
The `pdf_url` returned in `FormResult` points at `GET /results/{job_id}/pdf` and requires authentication (API key or JWT).
```python Python theme={null}
job_id = result.pdf_url.rstrip("/").split("/")[-2]
with open("filled.pdf", "wb") as out:
for chunk in client.results.get_pdf(job_id=job_id):
out.write(chunk)
```
```typescript TypeScript theme={null}
const jobId = result.pdf_url!.replace(/\/$/, "").split("/").slice(-2, -1)[0];
const pdfStream = await client.results.getPdf({ jobId });
// pdfStream is a ReadableStream; write to disk however you prefer.
```
```bash curl theme={null}
curl https://api.runpulse.com/results//pdf \
-H "x-api-key: YOUR_API_KEY" \
--output filled.pdf
```
## OpenAPI
````yaml POST /form/fill
openapi: 3.1.0
info:
title: Pulse API Structure
version: 0.1.0
description: >-
Canonical contract for the Pulse extraction APIs. This specification is the
single source of truth for shared request/response models that client and
server packages consume.
servers:
- url: https://api.runpulse.com
description: Default Pulse API base URL
security:
- ApiKey: []
paths:
/form/fill:
post:
tags:
- Form
summary: Fill form fields with new data
description: |-
Fill the fields of a PDF form with values inferred from a natural
language `instructions` prompt. Works on both AcroForm PDFs
(true form fields are written) and flat/scanned PDFs (values
are rendered as an overlay using detected cells from OCR).
**Input modes** — provide exactly one of:
- `form_id` — reuse a previously processed form from a prior
`/form/detect`, `/form/fill`, or `/form/clear` call. Skips
re-detection (fast path); the cached `form_fields` are
reused.
- `file_url` — public or pre-signed URL of a PDF Pulse will
download.
- `file` — direct binary upload of the PDF. Pulse runs cell
detection internally before filling.
All three input modes ride on the same `multipart/form-data`
request body. (Callers sending `Content-Type: application/json`
with `form_id` / `file_url` are still accepted server-side for
backward compatibility, but the SDKs only model the multipart
form.)
Optional `form_fields` lets callers supply or edit the detected
cells before filling. Optional `page_range` (alias `pages`,
e.g. `"1-3,5"`) restricts the operation to a subset of pages.
Synchronous by default — returns the filled `FormResult` inline
(including a `pdf_url` you can `GET` to download the PDF
binary). Set `async: true` to receive `{job_id, status:
"pending"}` and poll [GET /job/{jobId}](api:GET/job/{jobId}).
Billed at **3 credits per page**. Requires the `form_filler`
feature flag to be enabled for your organization.
operationId: formFill
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/FormFillMultipartInput'
responses:
'200':
description: Filled `FormResult` returned synchronously.
content:
application/json:
schema:
$ref: '#/components/schemas/FormResult'
'202':
description: >-
Async job accepted (`async: true`). Poll `GET /job/{jobId}` for the
result.
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncSubmissionResponse'
'400':
description: >-
Conflicting input (more than one of `form_id`, `file_url`, `file`),
missing `instructions`, or malformed `form_fields`.
'401':
description: Authentication failed or missing API key
'403':
description: Form filler not enabled for your organization
'404':
description: Referenced `form_id` not found
'429':
description: Rate limit exceeded
'500':
description: Internal server error
components:
schemas:
FormFillMultipartInput:
type: object
description: |-
`/form/fill` request body. All three input modes (`file`,
`file_url`, `form_id`) ride on this single `multipart/form-data`
schema; the server validates that exactly one is provided.
required:
- instructions
properties:
file:
type: string
format: binary
description: >-
Direct binary upload of the PDF. Mutually exclusive with `file_url`
and `form_id`.
file_url:
type: string
format: uri
description: >-
Public or pre-signed URL of a PDF Pulse will download. Mutually
exclusive with `file` and `form_id`.
form_id:
type: string
format: uuid
description: >-
Reference to a previously processed form. Mutually exclusive with
`file` / `file_url`.
instructions:
type: string
description: Required natural-language fill prompt.
form_fields:
type: string
description: >-
Optional JSON-encoded array of `FormCell` objects to override
detected cells. Multipart bodies must serialise this field as a
string.
page_range:
type: string
description: Restrict the operation to a subset of pages, e.g. `"1-3,5"`.
async:
type: string
description: >-
Set to `"true"` to run asynchronously and receive `{job_id, status}`
immediately.
FormResult:
type: object
description: |-
Result body returned by `/form/detect`, `/form/fill`, and
`/form/clear`. For async jobs (`async: true`) the same shape is
served back under `result` on
[GET /job/{jobId}](api:GET/job/{jobId}).
properties:
form_id:
type: string
format: uuid
description: >-
ID of the form record produced by this run. Pass to a subsequent
`/form/detect`, `/form/fill`, or `/form/clear` call as the single
input source to iterate without re-uploading the PDF.
page_count:
type: integer
minimum: 1
description: Number of pages in the output PDF.
pdf_url:
type: string
description: >-
URL to download the resulting PDF binary. Always points at [GET
/results/{jobId}/pdf](api:GET/results/{jobId}/pdf) for the
originating job. Authenticated callers can replay this URL until the
underlying artifact is garbage-collected.
form_fields:
type: array
description: >-
Detected cells of the resulting PDF (refreshed from the
filled/cleared output for fill/clear, or freshly detected for
`/form/detect`). Use these as a starting point for further edits.
items:
$ref: '#/components/schemas/FormCell'
fields_filled:
type: integer
minimum: 0
description: >-
Number of cells that were filled by this run. Present on
`/form/fill` responses only.
fields_cleared:
type: integer
minimum: 0
description: >-
Number of cells that were cleared by this run. Present on
`/form/clear` responses only.
credits_used:
type: number
format: float
description: >-
Number of credits consumed by **this request**. Detect charges 1
credit per page; fill and clear charge 3 credits per page.
plan_info:
allOf:
- $ref: '#/components/schemas/PlanInfo'
description: >-
Billing tier and cumulative usage information for the calling org,
including this form run.
AsyncSubmissionResponse:
type: object
description: >-
Acknowledgement returned when a request is submitted for asynchronous
processing. Poll `GET /job/{job_id}` to check status and retrieve
results.
required:
- job_id
- status
properties:
job_id:
type: string
description: Identifier assigned to the asynchronous job.
status:
type: string
description: Initial status reported by the server.
enum:
- pending
- processing
- completed
- failed
- canceled
message:
type: string
description: Human-readable description of the accepted job.
queuedAt:
type: string
format: date-time
deprecated: true
description: >-
**Deprecated** — Timestamp indicating when the job was accepted.
Retained for backward compatibility. Use `GET /job/{jobId}` for
timing details.
credits_used:
type: number
format: float
nullable: true
description: >-
Number of credits consumed by this request. Only present when the
organization has the credit billing system enabled.
FormCell:
type: object
description: |-
A single detected cell on a form page. Cells are produced by Pulse
cell detection during a `/form/detect`, `/form/fill`, or
`/form/clear` call and may be passed back via `form_fields` to
override what Pulse uses when filling or clearing.
All coordinate fields (`bounding_box`, `checkbox_coord`) are
normalized to `[0, 1]` relative to the page width / height, so
they're independent of the renderer's pixel resolution. Multiply
by your render width / height to convert to your own pixel space.
`page_number` is 1-indexed.
properties:
page_number:
type: integer
minimum: 1
description: 1-indexed page the cell belongs to.
bounding_box:
type: array
description: >-
Cell bounding box `[x1, y1, x2, y2]` normalized to the range `[0,
1]` (top-left origin). Same shape as the `bounding_box` field
returned by `/extract`.
items:
type: number
minimum: 0
maximum: 1
minItems: 4
maxItems: 4
text:
type: string
description: Current text content of the cell. Empty string for unfilled cells.
type:
type: string
description: >-
Detected cell type. Common values are `text`, `checkbox`, and
`signature`. Additional values may be returned as the detector
evolves.
enum:
- text
- checkbox
- signature
row:
type: integer
minimum: 0
description: >-
Row index inside the detected table this cell belongs to, when the
cell sits in a tabular region.
col:
type: integer
minimum: 0
description: >-
Column index inside the detected table this cell belongs to, when
the cell sits in a tabular region.
table_idx:
type: integer
minimum: 0
description: >-
Index of the detected table on the page this cell belongs to
(0-indexed). Cells outside any detected table may omit this field.
checkbox_details:
type: array
description: >-
Only present when `type == "checkbox"`. One entry per individual
checkbox inside this cell — a single cell often contains multiple
checkboxes (e.g. a "Filing Status" row with Single / MFJ / MFS / HoH
/ QSS). The cell-level `text` is the raw OCR'd line covering the
whole cell; per-box labels live here on each detail.
items:
$ref: '#/components/schemas/FormCheckboxDetail'
additionalProperties: false
PlanInfo:
type: object
description: >-
Cumulative billing snapshot for the calling organization. Sourced from
the `pulse-org-stats` aggregate table maintained asynchronously by the
org-stats Lambda; the in-flight request's contribution is added on top
so every response reflects post-request state. Returned by every
endpoint that consumes credits (extract, schema, tables, split, form,
and their batch / pipeline equivalents).
properties:
tier:
type: string
description: Billing tier, e.g. `"trial"`, `"growth"`, `"pulse_ultra_2"`.
total_credits_used:
type: number
format: float
description: >-
Total credits consumed by the organization to date, including this
request. The primary billing metric going forward.
pages_used:
type: integer
minimum: 0
description: >-
Total pages processed by the organization to date, including this
request. Kept for backward compatibility with clients that haven't
migrated to `total_credits_used`.
note:
type: string
description: >-
Optional human-readable note about billing state for this response
(e.g. trial credits remaining). Omitted when no note applies.
FormCheckboxDetail:
type: object
description: >-
A single checkbox inside a `FormCell` of `type == "checkbox"`. Bundles
the checkbox's normalized center coordinate, current selection state,
and the per-box text label.
properties:
center_coord:
type: array
description: >-
Normalized `[x, y]` center of the checkbox (in `[0, 1]`, top-left
origin), in the same coordinate system as `FormCell.bounding_box`.
items:
type: number
minimum: 0
maximum: 1
minItems: 2
maxItems: 2
selected:
type: boolean
description: >-
`true` when the checkbox is currently filled in (selected), `false`
otherwise.
text:
type: string
description: >-
Per-checkbox text label (e.g. `"Individual/sole proprietor"`, `"S
corporation"`). May be an empty string when no label could be
confidently associated with this specific box.
additionalProperties: false
securitySchemes:
ApiKey:
type: apiKey
in: header
name: x-api-key
x-fern-header:
name: apiKey
env: PULSE_API_KEY
````