Skip to main content
The Submission Parsing API runs the AI parsing pipeline over documents you have already uploaded. You upload and finalize a file (or a folder of files) through the Company Files API, then explicitly trigger a parse over those targets for a chosen flow. Parsing runs asynchronously; you poll its outcome with the List Parse Runs endpoint.

​
Key Concepts

  • Flow — what the parse produces. There are two flows: submission parses a document into a structured submission, and policy parses it into a structured policy.
  • Target — what a parse runs over: a single fileId, or a folderId (the folder is recursively flattened to its live, ready files and parsed together as one run). A folder of N documents is one run, not N.
  • Parse run — one task in the pipeline. A trigger first enqueues the flow-agnostic extract stage, which hands off to the per-flow create_<flow>_v<N> stage. Each of these tasks is its own run record in the listing.
  • Idempotent per-target dedupe — re-triggering the same target for the same flow collapses to a duplicate outcome instead of enqueuing the work twice, so retries and double-calls are safe.

​
API Endpoints

​
Permissions

​
How It Works

  1. Upload and finalize the document(s) through the Company Files API — create an upload intent, PUT the bytes to the signed URL, then finalize so the file is ready. (Finalize no longer parses; parsing is reachable only via trigger-parse.)
  2. Trigger the parse over the finalized file(s) and/or folder(s) for a flow (submission or policy). The response returns one outcome per target, each with the resolved parseTaskName, an enqueued/duplicate outcome, and a runId.
  3. Poll the runs with List Parse Runs until they reach a terminal status.

​
Run Lifecycle

A run’s status is one of:
  • running — the run is in flight (or waiting on scanning / retrying).
  • succeeded — the run completed.
  • failed — the run failed terminally. The internal retry states (failed_retrying, failed_permanent, failed_vanished) all collapse to failed; a failed run that recorded a message surfaces it on the error field.
Content that has not finished malware scanning is safe to trigger — the extract stage self-gates and backs off until every file in the target is ready.

​
Example: Parse an Uploaded Submission

To parse a whole folder as a policy instead, send a folderIds array with the policy flow. Provide at least one of fileIds or folderIds.
Listing is a flat, per-task view. Each run record is one pipeline task, not one logical end-to-end run: runId is the task row’s id, flow is null for the flow-agnostic extract stage, and target is currently always null (the specific file or folder a run parsed is not yet persisted on the run row).