Skip to main content
POST
/
form
/
clear
Clear PDF Form
curl --request POST \
  --url https://api.runpulse.com/form/clear \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "page_range": "<string>",
  "async": false,
  "form_fields": [
    {
      "page_number": 2,
      "bounding_box": [
        0.5
      ],
      "text": "<string>",
      "type": "text",
      "row": 1,
      "col": 1,
      "table_idx": 1,
      "checkbox_details": [
        {
          "center_coord": [
            0.5
          ],
          "selected": true,
          "text": "<string>"
        }
      ]
    }
  ],
  "form_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "file_url": "<string>",
  "instructions": "Clear only the signature and date fields."
}
'
{
  "form_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "page_count": 2,
  "form_fields": [
    {
      "page_number": 2,
      "bounding_box": [
        0.5
      ],
      "text": "<string>",
      "type": "text",
      "row": 1,
      "col": 1,
      "table_idx": 1,
      "checkbox_details": [
        {
          "center_coord": [
            0.5
          ],
          "selected": true,
          "text": "<string>"
        }
      ]
    }
  ],
  "pdf_url": "<string>",
  "fields_filled": 1,
  "fields_cleared": 1,
  "credits_used": 123,
  "plan_info": {
    "tier": "<string>",
    "total_credits_used": 123,
    "pages_used": 1
  }
}

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.

​
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 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, /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: direct PDF upload (multipart only).
Sending more than one (or none) returns 400.

​
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

FieldTypeRequiredDescription
form_idstring (uuid)One of theseReuse a previously processed form. Skips re-upload and re-detection.
file_urlstring (uri)One of thesePublic or presigned URL of a PDF to download and clear.
filebinaryOne of theseDirect PDF upload (multipart only).
instructionsstringNoOptional natural-language scoping prompt. When omitted, every user-filled value is cleared and the printed template is preserved.
form_fieldsarray of FormCellNoOptional override for the cells used when clearing.
page_rangestringNo1-based page filter, for example "1,3-5". Alias pages accepted.
asyncbooleanNoWhen 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 response, with fields_cleared substituted for fields_filled.
FieldTypeDescription
form_idstring (uuid)ID of the new form record produced by this run. Pass back via form_id to chain.
page_countintegerNumber of pages in the output PDF.
pdf_urlstring (uri)URL to download the cleared PDF binary. Always points at GET /results/jobId/pdf. Requires the same auth as the rest of the API.
form_fieldsarray of FormCellDetected cells of the resulting (cleared) PDF, refreshed after the clear.
fields_clearedintegerNumber 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_usednumberCredits consumed by this request (3 × page_count).
plan_infoobject{ tier, total_credits_used, pages_used } cumulative billing snapshot for your organization (post-request).
{
  "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: 
{
  "job_id": "abc123-def456-ghi789",
  "status": "pending"
}
Poll GET /job/jobId. The job’s result carries the same FormResult shape that the sync flow would have returned inline.

​
Status Codes

CodeDescription
200Cleared FormResult returned synchronously.
202Async job accepted (async: true). Poll /job/{jobId} for the result.
400Missing PDF, more than one PDF source provided, or malformed form_fields.
401Authentication failed or missing API key.
404Referenced form_id not found (or belongs to a different org).
500Internal server error.

​
Example Usage

​
Clear All User Input

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}")

​
Scoped Clear

Pass instructions to clear only specific fields. 
result = client.form.clear(
    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. 
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.",
)

​
Async Clear With Polling

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']}")

Authorizations

​
x-api-key
string
header
required

API key for authentication

Body

JSON body for POST /form/clear. Provide exactly one of form_id or file_url (or use the multipart variant to upload a file).

​
page_range
string

Restrict the operation to a subset of pages. Accepts comma-separated page numbers and ranges, e.g. "1-3,5". Alias: pages.

​
async
boolean
default:false

When true, the endpoint returns immediately with { job_id, status: "pending" } (HTTP 202) and processes the job in the background. Poll GET /job/{jobId} for the result.

​
form_fields
object[]

Optional override for the cells used when filling or clearing. When omitted, Pulse uses the cells stored on the referenced form_id, or detects them from the uploaded PDF.

​
form_id
string<uuid>

ID returned by a previous /form/detect, /form/fill, or /form/clear call. Reuses the stored PDF without re-uploading.

​
file_url
string<uri>

Public or presigned URL of a PDF to download and clear.

​
instructions
string

Optional natural-language description of what to clear. When omitted, every user-filled value is cleared while the printed template is preserved.

Example:

"Clear only the signature and date fields."

Response

Cleared FormResult returned synchronously.

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

​
form_id
string<uuid>
required

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
integer
required

Number of pages in the output PDF.

Required range: x >= 1
​
form_fields
object[]
required

Detected cells of the resulting PDF (refreshed from the filled / cleared output for fill / clear, or freshly detected for /form/detect).

​
pdf_url
string

URL to download the resulting PDF binary. Always points at GET /results/{jobId}/pdf for the originating job. Requires the same authentication (API key or JWT) as the rest of the API.

​
fields_filled
integer

Number of cells whose value actually changed during this run. Present on /form/fill responses only.

Required range: x >= 0
​
fields_cleared
integer

Number of cells whose value actually changed during this run (no-op clears on already-empty fields are not counted). Present on /form/clear responses only.

Required range: x >= 0
​
credits_used
number<float>

Credits consumed by this request. Detect charges 1 credit per page; fill and clear charge 3 credits per page.

​
plan_info
object

Cumulative billing snapshot for the calling organization. Includes the in-flight request's contribution, so every response reflects post-request state.