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 creates three things: a submission, an in-progress quote that holds what the parser read from the application, and the exposures the quote covers. The submission ties them together and holds any loss history the parser found. policy reads the document as an existing policy and creates the same three things. Neither flow binds: someone reviews the quote and finishes it in the app, where its Forms steps add its recommended forms from the quote as they leave it. The parse attaches none.
  • 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).