> ## 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. # Start Invoice Bill Review > Starts a bill review of the invoice against the company's bill review rules and answers `202` immediately with the `runId` to poll. **Nothing is reviewed inside this request.** The review runs as background work, so a `202` means the run was created and dispatched — not that a verdict exists. Read it with [Get Invoice Bill Review](/api-reference/financials/get-invoice-bill-review). **There is no request body.** The rules are the company's own and are snapshotted when the run is created, and the invoice version is pinned from its current head — so there is nothing for a caller to send. No `actionId` and no `If-Match` either: a bill review reads the invoice and records a verdict beside it, it does not journal an action against the document. **Re-posting is safe.** While a review of this invoice is queued or running, a second call creates nothing and answers `202` with `outcome: in_flight` and the id of the run ALREADY under way. Once that run is terminal, the next call mints a fresh one — re-reviewing an invoice is a legitimate thing to want, so this is not deduplicated indefinitely. **Capacity (`429`).** Background work is capped per company. A call made while the company is at that cap is refused outright, with a message naming both numbers; nothing is queued. Retry once some of the work in flight has finished. **Required permission:** `company.payment:update` ## OpenAPI ````yaml /openapi/generated-external-api.yaml post /api/v1/companies/{companyId}/financials/invoices/{invoiceId}/bill-review 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}/financials/invoices/{invoiceId}/bill-review: post: tags: - Financials summary: Start Invoice Bill Review description: > Starts a bill review of the invoice against the company's bill review rules and answers `202` immediately with the `runId` to poll. **Nothing is reviewed inside this request.** The review runs as background work, so a `202` means the run was created and dispatched — not that a verdict exists. Read it with [Get Invoice Bill Review](/api-reference/financials/get-invoice-bill-review). **There is no request body.** The rules are the company's own and are snapshotted when the run is created, and the invoice version is pinned from its current head — so there is nothing for a caller to send. No `actionId` and no `If-Match` either: a bill review reads the invoice and records a verdict beside it, it does not journal an action against the document. **Re-posting is safe.** While a review of this invoice is queued or running, a second call creates nothing and answers `202` with `outcome: in_flight` and the id of the run ALREADY under way. Once that run is terminal, the next call mints a fresh one — re-reviewing an invoice is a legitimate thing to want, so this is not deduplicated indefinitely. **Capacity (`429`).** Background work is capped per company. A call made while the company is at that cap is refused outright, with a message naming both numbers; nothing is queued. Retry once some of the work in flight has finished. **Required permission:** `company.payment:update` operationId: startFinancialsInvoiceBillReview parameters: - $ref: '#/components/parameters/companyId' - name: invoiceId in: path required: true schema: type: string format: uuid description: Invoice identifier responses: '202': description: >- Accepted — the review was queued (or one was already under way); poll `runId` content: application/json: schema: type: object required: - runId - outcome properties: runId: type: string format: uuid description: >- The bill-review run to poll. On `in_flight` this is the run that was ALREADY under way, not a new one outcome: type: string enum: - enqueued - in_flight - duplicate description: >- `enqueued` when a fresh run was created and dispatched; `in_flight` when a review of this invoice was already queued or running (nothing new was created); `duplicate` when the task transport had already seen this run id — each request mints a fresh run, so it should not occur, and is reported rather than hidden examples: enqueued: summary: A fresh review was queued value: runId: 994bfc11-8ff3-485a-89ff-7839c9bb6101 outcome: enqueued inFlight: summary: A review of this invoice was already under way value: runId: 994bfc11-8ff3-485a-89ff-7839c9bb6101 outcome: in_flight '400': description: Bad Request — a non-uuid `invoiceId`, or an unknown query parameter content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: Not Found — no invoice with this id for this company content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invoiceNotFound: summary: Invoice not found value: error: code: NotFoundError message: Invoice not found userMessages: - Invoice not found '429': description: > Too Many Requests — the company is at its background-work capacity, so nothing was queued. Wait for some of the work already running to finish, then retry. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: noCapacity: summary: No room for another background run right now value: error: code: SelectionExceedsAuditCapacity message: >- You've selected 1 transaction; there is room for none right now. Wait for some of the background work already running to finish, then try again. '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. ````