> ## Documentation Index
> Fetch the complete documentation index at: https://docs.go.aiinsurance.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Parse uploaded documents into structured submissions and policies

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](/api-reference/company-files/overview), 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

| Method | Endpoint                  | Description                                                      |
| ------ | ------------------------- | ---------------------------------------------------------------- |
| POST   | `/v1/files/trigger-parse` | Kick the parsing pipeline over files and/or folders for one flow |
| GET    | `/v1/files/parse-runs`    | List parse runs, newest-first, to poll their outcome             |

## Permissions

| Operation       | Permission            |
| --------------- | --------------------- |
| Trigger Parse   | `company.file:create` |
| List Parse Runs | `company.file:read`   |

## How It Works

1. **Upload and finalize** the document(s) through the
   [Company Files API](/api-reference/company-files/overview) — 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

```bash theme={null}
# 1. Trigger a submission parse over two finalized files
curl -X POST https://go.aiinsurance.io/api/v1/companies/{companyId}/files/trigger-parse \
  -H "Authorization: YOUR-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "submission",
    "fileIds": [
      "550e8400-e29b-41d4-a716-446655440020",
      "550e8400-e29b-41d4-a716-446655440030"
    ]
  }'
# → {
#     "flow": "submission",
#     "enqueued": [
#       {"target": {"kind": "file", "id": "...440020"}, "parseTaskName": "create_submission_v1", "outcome": "enqueued", "runId": "..."},
#       {"target": {"kind": "file", "id": "...440030"}, "parseTaskName": "create_submission_v1", "outcome": "enqueued", "runId": "..."}
#     ]
#   }

# 2. Poll the runs until they reach a terminal status
curl "https://go.aiinsurance.io/api/v1/companies/{companyId}/files/parse-runs?page=1&pageSize=20" \
  -H "Authorization: YOUR-API-KEY"
# → {"items": [{"runId": "...", "flow": "submission", "status": "running", ...}, ...], "totalCount": 2}
```

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

<Note>
  **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).
</Note>

## Related Resources

* [Company Files API](/api-reference/company-files/overview) — upload and finalize the documents you parse
* [Entities API](/api-reference/entities/overview) — the submissions and policies parsing produces
* [Roadmap](/api-reference/roadmap) — overall API direction