Detect Form Fields
Run cell detection on a PDF and return the detected form_fields
along with a reusable form_id. No LLM matching, no fill, no
clear — this is the OCR / layout step that /form/fill and
/form/clear would otherwise run internally.
The returned form_id references the uploaded PDF and its
detected layout, and can be passed back to a subsequent
/form/fill, /form/clear, or /form/detect call as the
single input source — Pulse will skip detection on the fast
path and reuse the cached cells.
Input modes — provide exactly one of:
form_id— re-detect cells on a previously stored PDF. Useful when callers want to refresh layout after editing or when chaining detect calls.file_url— public or pre-signed URL 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.)
Optional page_range (alias pages, e.g. "1-3,5") restricts
the operation to a subset of pages.
Synchronous by default — returns the detected layout inline.
Set async: true to receive {job_id, status: "pending"}
immediately and poll GET /job/.
Billed at 1 credit per page. Requires the form_filler
feature flag to be enabled for your organization.
Overview
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/clearcall). 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.
400.
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-levelcredits_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.
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:
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
Passform_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
Body
/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.
Direct binary upload of the PDF. Mutually exclusive with file_url and form_id.
Public or pre-signed URL of a PDF Pulse will download. Mutually exclusive with file and form_id.
Reference to a previously processed form. Mutually exclusive with file / file_url.
Restrict the operation to a subset of pages, e.g. "1-3,5".
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].
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.
Number of pages in the output PDF.
x >= 1URL 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.
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.
Number of cells that were filled by this run. Present on /form/fill responses only.
x >= 0Number of cells that were cleared by this run. Present on /form/clear responses only.
x >= 0Number of credits consumed by this request. Detect charges 1 credit per page; fill and clear charge 3 credits per page.
Billing tier and cumulative usage information for the calling org, including this form run.