> ## 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. # Trigger Parse > Explicitly kick the parsing pipeline over one or more files **and/or folders** that were already uploaded and finalized. For each target the server resolves the parse-stage task from `{company, flow}` and enqueues the extract step, which then hands off to the resolved `create__v` task. Each target becomes ONE parse run: a `fileId` parses that single file, and a `folderId` recursively flattens the folder to its live, ready files and parses them together as one run (a folder of N documents is one run, not N). Provide at least one of `fileIds` or `folderIds`. This is the only way to start parsing: upload and finalize a file (or a folder of files), then POST here to parse it. 3rd-party callers and the inbound-email forwarder both use this to parse (or re-parse) content uploaded earlier. Poll the outcome with **List Parse Runs**. Enqueuing is idempotent at the boundary: re-posting the same target for the same flow collapses to `duplicate` outcomes rather than enqueuing twice. Set `force: true` to bypass this dedupe and force a fresh run for each target. Content that has not finished scanning is safe to trigger — extract self-gates and backs off until every file in the target is `ready`. A folder that is an email-sourced import from a sender the company has not recognized is never parsed: its outcome is `skipped_unrecognized_sender` (with `runId: null`) and no run is created. An operator can recognize the sender on the in-app Imports page to make the folder parseable. **Required permission:** `company.file:create` ## OpenAPI ````yaml /openapi/generated-external-api.yaml post /api/v1/companies/{companyId}/files/trigger-parse openapi: 3.0.3 info: title: AI Insurance External API description: External API for AI Insurance platform version: 1.0.0 contact: email: support@aiinsurance.io servers: - url: https://go.aiinsurance.io description: Production security: - ApiKeyAuth: [] paths: /api/v1/companies/{companyId}/files/trigger-parse: post: tags: - Submission Parsing summary: Trigger Parse description: > Explicitly kick the parsing pipeline over one or more files **and/or folders** that were already uploaded and finalized. For each target the server resolves the parse-stage task from `{company, flow}` and enqueues the extract step, which then hands off to the resolved `create__v` task. Each target becomes ONE parse run: a `fileId` parses that single file, and a `folderId` recursively flattens the folder to its live, ready files and parses them together as one run (a folder of N documents is one run, not N). Provide at least one of `fileIds` or `folderIds`. This is the only way to start parsing: upload and finalize a file (or a folder of files), then POST here to parse it. 3rd-party callers and the inbound-email forwarder both use this to parse (or re-parse) content uploaded earlier. Poll the outcome with **List Parse Runs**. Enqueuing is idempotent at the boundary: re-posting the same target for the same flow collapses to `duplicate` outcomes rather than enqueuing twice. Set `force: true` to bypass this dedupe and force a fresh run for each target. Content that has not finished scanning is safe to trigger — extract self-gates and backs off until every file in the target is `ready`. A folder that is an email-sourced import from a sender the company has not recognized is never parsed: its outcome is `skipped_unrecognized_sender` (with `runId: null`) and no run is created. An operator can recognize the sender on the in-app Imports page to make the folder parseable. **Required permission:** `company.file:create` operationId: triggerCompanyFileParse parameters: - $ref: '#/components/parameters/companyId' requestBody: required: true content: application/json: schema: type: object required: - flow properties: flow: type: string enum: - submission - policy description: Which parsing flow to run for these targets. fileIds: type: array items: type: string format: uuid description: >- Ids of already-uploaded, finalized files to parse (each a run of one file). Optional, but provide at least one of `fileIds` or `folderIds`. folderIds: type: array items: type: string format: uuid description: >- Ids of folders to parse. Each folder is recursively flattened to its live, ready files and parsed together as a single run. Optional, but provide at least one of `fileIds` or `folderIds`. parseVersionOverride: type: string description: >- Optional pin for the parse-stage task version (e.g. `create_submission_v1`). Must be a registered parse-stage task name or the request is rejected with a `400`. force: type: boolean default: false description: >- Blind re-trigger. When `true`, bypass the per-target dedupe so each requested target always mints a fresh run (a full extract+parse) instead of collapsing to `duplicate`. Defaults to `false`, which keeps the idempotent dedupe behavior. examples: triggerSubmissionParse: summary: Parse two uploaded files as submissions value: flow: submission fileIds: - 550e8400-e29b-41d4-a716-446655440020 - 550e8400-e29b-41d4-a716-446655440030 triggerFolderParse: summary: Parse a whole folder as a policy value: flow: policy folderIds: - 550e8400-e29b-41d4-a716-446655440040 responses: '200': description: >- Parse enqueued — one outcome per requested target, in request order (files then folders) content: application/json: schema: type: object properties: flow: type: string enum: - submission - policy description: The flow the targets were enqueued for enqueued: type: array items: type: object properties: target: type: object description: The file or folder this outcome is for properties: kind: type: string enum: - file - folder id: type: string format: uuid parseTaskName: type: string nullable: true description: >- The resolved `create__v` task that will run after extract; `null` when the target was skipped outcome: type: string enum: - enqueued - duplicate - skipped_unrecognized_sender description: >- `enqueued` on first call; `duplicate` when the same target for the same flow was already enqueued (dedupe); `skipped_unrecognized_sender` when the folder is an email-sourced import whose sender the company has not recognized — no run is created until an operator recognizes the sender on the Imports page runId: type: string nullable: true description: >- The parse-run id minted for this target (names the ephemeral run folder the extraction is built in); `null` when the target was skipped examples: success: summary: A file and a folder enqueued value: flow: submission enqueued: - target: kind: file id: 550e8400-e29b-41d4-a716-446655440020 parseTaskName: create_submission_v1 outcome: enqueued runId: 994bfc11-8ff3-485a-89ff-7839c9bb6101 - target: kind: folder id: 550e8400-e29b-41d4-a716-446655440040 parseTaskName: create_submission_v1 outcome: enqueued runId: 0f204eac-17e5-42bc-93b1-0dd2aea57baa '400': description: >- Bad Request — missing/unknown `flow`, neither `fileIds` nor `folderIds` provided, a non-uuid id, or an unregistered `parseVersionOverride` content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unknownFlow: summary: Unknown flow value: error: code: InvalidProperties message: 'Invalid option: expected one of "submission"|"policy"' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalServerError' components: parameters: companyId: name: companyId in: path required: true schema: type: string format: uuid description: Company identifier schemas: ErrorResponse: type: object description: Standard error response for all external API endpoints required: - error properties: error: type: object required: - code - message properties: code: type: string description: Machine-readable error code example: VALIDATION_ERROR message: type: string description: Human-readable error message example: 'submissionId: Required field is missing' userMessages: type: array description: >- Clean, verbatim-displayable messages — one entry per failure, free of error-code tags, field paths, and internal noise. Suitable for showing to end users as-is. items: type: string example: - Exposures of type 'company' require an address details: type: array description: Additional details for validation errors (field-level errors) items: type: object properties: field: type: string description: The field that caused the error example: submissionId message: type: string description: Description of the field error example: Required field is missing responses: Unauthorized: description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingApiKey: summary: Missing API key value: error: code: AuthenticationError message: API key authentication required userMessages: - API key authentication required invalidApiKey: summary: >- Invalid API key (e.g. unknown key, or a Bearer token used instead of an API key) value: error: code: AuthenticationError message: Invalid API key userMessages: - Invalid API key Forbidden: description: Forbidden - Insufficient permissions content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: insufficientPermissions: summary: Insufficient permissions value: error: code: AuthorizationError message: User is not authorized to perform the requested action userMessages: - User is not authorized to perform the requested action companyMismatch: summary: A valid API key naming another company in the URL value: error: code: AuthorizationError message: API key is not scoped to the requested company userMessages: - API key is not scoped to the requested company InternalServerError: description: Internal Server Error - Unexpected error occurred content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internalError: summary: Unexpected server error value: error: code: UncaughtActionError message: Uncaught error occurred in userMessages: - An unexpected error occurred. Please try again later. securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: >- API key authentication. Send your raw API key as the `Authorization` header value with NO scheme prefix — `Authorization: YOUR-API-KEY`. Do NOT prefix it with `Bearer ` or `ApiKey `, and do not use an `X-API-Key` header; those are not accepted. ````