Skip to main content
POST
Detect form fields on a PDF

Overview

Detect form fields on a PDF and return them as structured cells along with a reusable form_id. Returns a FormResult synchronously by default. Set async: true to run in the background and poll GET /job/jobId for the result.
/form/detect is the entry point for the form-filler workflow when you want to inspect the fields Pulse identified on a PDF before filling or clearing them. Use it to preview detected fields, fix a misclassified cell, see which checkboxes are currently selected, or cache the detection result for repeated chained calls. The returned form_id references the uploaded PDF and its detected layout, and can be passed back to any of /form/detect, /form/fill, or /form/clear as the single input source. Pulse will reuse the cached layout instead of re-detecting it.

Providing the PDF

Provide the PDF in exactly one of the following ways:
  • form_id: re-detect on a previously stored PDF (returned by an earlier /form/detect, /form/fill, or /form/clear call). Useful when chaining detect calls or refreshing layout after edits.
  • 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 1 credit per page of the PDF being processed. 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


Response

Sync (200): FormResult

When async is false (default), the call returns a FormResult body directly. Since /form/detect does not modify the PDF, neither fields_filled nor fields_cleared is present.
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:
Poll GET /job/jobId. The job’s result carries the same FormResult shape that the sync flow would have returned inline.

Status Codes


Example Usage

Detect From URL

File Upload

Detect, Edit, Then Fill

Detect the cells once, hand-edit any that were misclassified, and pass the edited cells back to /form/fill along with the cached form_id. The fill call reuses the cached layout instead of re-detecting it.

Re-detect On A Stored Form

Pass form_id (instead of file_url / file) to refresh the layout on a PDF already stored by Pulse. Useful after a /form/clear round-trip, or to grab the latest cells if you suspect drift.

Authorizations

x-api-key
string
header
required

Body

multipart/form-data

/form/detect 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.

file
file

Direct binary upload of the PDF. Mutually exclusive with file_url and form_id.

file_url
string<uri>

Public or pre-signed URL of a PDF Pulse will download. Mutually exclusive with file and form_id.

form_id
string<uuid>

Reference to a previously processed form. Mutually exclusive with file / file_url.

page_range
string

Restrict the operation to a subset of pages, e.g. "1-3,5".

async
string

Set to "true" to run asynchronously and receive {job_id, status} immediately.

Response

Detected layout 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} [blocked].

form_id
string<uuid>

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

Number of pages in the output PDF.

Required range: x >= 1
pdf_url
string

URL to download the resulting PDF binary. Always points at GET /results/{jobId}/pdf [blocked] for the originating job. Authenticated callers can replay this URL until the underlying artifact is garbage-collected.

form_fields
object[]

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.

fields_filled
integer

Number of cells that were filled by this run. Present on /form/fill responses only.

Required range: x >= 0
fields_cleared
integer

Number of cells that were cleared by this run. Present on /form/clear responses only.

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

Number of 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.