Clear Form - Pulse API

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>",
      "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>",
      "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,
    "note": "<string>"
  }
}

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>",
      "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>",
      "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,
    "note": "<string>"
  }
}

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: 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`	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 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. 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).

{
  "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

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

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.

Show child attributes

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

Show child attributes

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

Billing tier and cumulative usage information for the calling org, including this form run.

Show child attributes

Fill Form Extract File Async (Deprecated)

⌘I

​Overview

​Providing the PDF

​Pricing

​Request

​Request Body

​Response

​Sync (200): FormResult

​Async (202): FormJobAccepted

​Status Codes

​Example Usage

​Clear All User Input

​Scoped Clear

​Chain Fill, Clear, Fill

​Async Clear With Polling

Authorizations

Body

Response

Overview

Providing the PDF

Pricing

Request

Request Body

Response

Sync (200): `FormResult`

Async (202): `FormJobAccepted`

Status Codes

Example Usage

Clear All User Input

Scoped Clear

Chain Fill, Clear, Fill

Async Clear With Polling