> ## 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.
# Clear Form
> Remove user-entered data from a PDF form, leaving the blank
form template intact. Erases handwritten entries, typed values,
and unchecks selected checkboxes — printed labels, field
titles, section headers, and other static template content are
preserved.
**Input modes** — provide exactly one of:
- `form_id` — reuse a previously processed form from a prior
`/form/detect`, `/form/fill`, or `/form/clear` call (fast
path; cached layout reused).
- `file_url` — public or pre-signed URL of a PDF Pulse will
download.
- `file` — direct binary upload of the PDF.
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.)
`instructions` is optional. When omitted, Pulse clears every
user-filled field deterministically (no LLM call) on AcroForm
PDFs, eliminating any chance of hallucinated content. Provide
a natural language prompt to clear only specific fields
(e.g. `"clear only the address fields"`); targeted clears go
through the LLM matcher with a delete-only filter.
Optional `form_fields` and `page_range` (alias `pages`) behave
the same as on [Form Fill](api:POST/form/fill).
Synchronous by default — returns the cleared `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
Remove user-filled values from a PDF form while preserving the original printed template (labels, headers, instructions, structural text). Returns a `FormResult` synchronously by default. Set `async: true` to run in the background and poll [GET /job/{'{'}jobId{'}'}](/api-reference/endpoint/poll) for the result.
`/form/clear` strips handwritten entries, typed responses, and selected checkbox marks from a PDF without altering the blank template underneath.
`instructions` is **optional**:
* **Omit** to clear every user-filled value on the form.
* **Provide** a natural-language prompt (for example `"clear only the address fields"`) to scope the clear to specific 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`](/api-reference/endpoint/form-fill), or `/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 cleared. 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 clear. |
| `file` | binary | One of these | PDF uploaded inline with the request. |
| `instructions` | string | No | Optional natural-language scoping prompt. When omitted, every user-filled value is cleared and the printed template is preserved. |
| `form_fields` | array of [`FormCell`](/api-reference/endpoint/form-fill#response.body.form_fields) | No | Optional override for the cells used when clearing. |
| `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`
Mirrors the [`/form/fill`](/api-reference/endpoint/form-fill#response) response, with `fields_cleared` substituted for `fields_filled`.
| Field | Type | Description |
| ---------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `form_id` | string (uuid) | ID of the new form record produced by this run. Pass back via `form_id` to chain. |
| `page_count` | integer | Number of pages in the output PDF. |
| `pdf_url` | string (uri) | URL to download the cleared PDF binary. Always points at [GET /results/{'{'}jobId{'}'}/pdf](/api-reference/endpoint/poll). Requires the same auth as the rest of the API. |
| `form_fields` | array of `FormCell` | Detected cells of the resulting (cleared) PDF, refreshed after the clear. |
| `fields_cleared` | integer | Number of cells whose value actually changed during this run. Fields that were already empty are **not** counted, so on an empty template this returns `0` even when many fields exist. |
| `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": "98056c28-569b-4689-a34a-396a68a66d4b",
"page_count": 6,
"pdf_url": "https://api.runpulse.com/results/933f730a-4b78-4b8a-bfd5-8aff3d6c880d/pdf",
"form_fields": [ /* refreshed cells of the cleared PDF */ ],
"fields_cleared": 23,
"credits_used": 18.0,
"plan_info": {
"tier": "pulse_ultra_2",
"total_credits_used": 1302.0,
"pages_used": 434
}
}
```
### 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 | Cleared `FormResult` returned synchronously. |
| 202 | Async job accepted (`async: true`). Poll `/job/{jobId}` for the result. |
| 400 | Missing PDF, more than one PDF source provided, 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
### Clear All User Input
```python Python theme={null}
from pulse import Pulse
client = Pulse(api_key="YOUR_API_KEY")
result = client.form.clear(
file_url="https://example.com/filled-form.pdf",
)
print(f"form_id={result.form_id}")
print(f"fields_cleared={result.fields_cleared}")
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.clear({
file_url: "https://example.com/filled-form.pdf",
});
console.log(`form_id=${result.form_id}`);
console.log(`fields_cleared=${result.fields_cleared}`);
console.log(`download: ${result.pdf_url}`);
```
```bash curl theme={null}
curl -X POST https://api.runpulse.com/form/clear \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"file_url": "https://example.com/filled-form.pdf"
}'
```
### Scoped Clear
Pass `instructions` to clear only specific fields.
```python Python theme={null}
result = client.form.clear(
file_url="https://example.com/filled-form.pdf",
instructions="Clear only the signature and date fields.",
)
```
```typescript TypeScript theme={null}
const result = await client.form.clear({
file_url: "https://example.com/filled-form.pdf",
instructions: "Clear only the signature and date fields.",
});
```
```bash curl theme={null}
curl -X POST https://api.runpulse.com/form/clear \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"file_url": "https://example.com/filled-form.pdf",
"instructions": "Clear only the signature and date fields."
}'
```
### Chain Fill, Clear, Fill
Clear an existing filled form and immediately re-fill it with new values without re-uploading the PDF. The `form_id` returned by each step is the hand-off.
```python Python theme={null}
filled = client.form.fill(
file_url="https://example.com/intake-form.pdf",
instructions="Fill in patient name as John Smith.",
)
cleared = client.form.clear(form_id=filled.form_id)
refilled = client.form.fill(
form_id=cleared.form_id,
instructions="Fill in patient name as Jane Doe.",
)
```
```typescript TypeScript theme={null}
const filled = await client.form.fill({
file_url: "https://example.com/intake-form.pdf",
instructions: "Fill in patient name as John Smith.",
});
const cleared = await client.form.clear({ form_id: filled.form_id! });
const refilled = await client.form.fill({
form_id: cleared.form_id!,
instructions: "Fill in patient name as Jane Doe.",
});
```
```bash curl theme={null}
# Step 1: fill
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 John Smith."}'
# Step 2: clear by form_id
curl -X POST https://api.runpulse.com/form/clear \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"form_id": ""}'
# Step 3: fill again by form_id
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."}'
```
### Async Clear With Polling
```python Python theme={null}
import time
submission = client.form.clear(
file_url="https://example.com/big-filled-form.pdf",
async_=True,
)
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
print(f"fields_cleared={result['fields_cleared']} pdf_url={result['pdf_url']}")
```
```bash curl theme={null}
curl -X POST https://api.runpulse.com/form/clear \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"file_url": "https://example.com/big-filled-form.pdf",
"async": true
}'
```
## OpenAPI
````yaml POST /form/clear
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/clear:
post:
tags:
- Form
summary: Clear filled data from a form
description: |-
Remove user-entered data from a PDF form, leaving the blank
form template intact. Erases handwritten entries, typed values,
and unchecks selected checkboxes — printed labels, field
titles, section headers, and other static template content are
preserved.
**Input modes** — provide exactly one of:
- `form_id` — reuse a previously processed form from a prior
`/form/detect`, `/form/fill`, or `/form/clear` call (fast
path; cached layout reused).
- `file_url` — public or pre-signed URL of a PDF Pulse will
download.
- `file` — direct binary upload of the PDF.
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.)
`instructions` is optional. When omitted, Pulse clears every
user-filled field deterministically (no LLM call) on AcroForm
PDFs, eliminating any chance of hallucinated content. Provide
a natural language prompt to clear only specific fields
(e.g. `"clear only the address fields"`); targeted clears go
through the LLM matcher with a delete-only filter.
Optional `form_fields` and `page_range` (alias `pages`) behave
the same as on [Form Fill](api:POST/form/fill).
Synchronous by default — returns the cleared `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: formClear
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/FormClearMultipartInput'
responses:
'200':
description: Cleared `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`)
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:
FormClearMultipartInput:
type: object
description: |-
`/form/clear` 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.
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: >-
Optional natural language description of what to clear. When
omitted, Pulse clears everything user-filled deterministically.
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
````