> ## 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. # List Invoices > Returns the company's invoices — global and entity-scoped lists in one endpoint. All filters AND together; `status` is an OR within its column; date bounds are inclusive; `unlinked=true` matches invoices with no event AND no policy link (`false` applies no filter). Deleted invoices are hidden (the [detail read](/api-reference/financials/get-invoice) returns them). Cursor-paginated: pass the previous page's `nextCursor` back as `cursor` until it is `null`. Rows are ordered by last update, newest first. Every row carries `headJournalId`, so list-driven writes have their `If-Match` watermark. **Required permission:** `company.payment:read` ## OpenAPI ````yaml /openapi/generated-external-api.yaml get /api/v1/companies/{companyId}/financials/invoices 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: get: tags: - Financials summary: List Invoices description: > Returns the company's invoices — global and entity-scoped lists in one endpoint. All filters AND together; `status` is an OR within its column; date bounds are inclusive; `unlinked=true` matches invoices with no event AND no policy link (`false` applies no filter). Deleted invoices are hidden (the [detail read](/api-reference/financials/get-invoice) returns them). Cursor-paginated: pass the previous page's `nextCursor` back as `cursor` until it is `null`. Rows are ordered by last update, newest first. Every row carries `headJournalId`, so list-driven writes have their `If-Match` watermark. **Required permission:** `company.payment:read` operationId: listFinancialsInvoices parameters: - $ref: '#/components/parameters/companyId' - name: status in: query schema: type: string description: >- Comma-separated invoice statuses (OR within the column) — any of `no_charges`, `owed`, `partially_paid`, `paid`, `voided`. `deleted` is rejected (`400`): deleted invoices are hidden from lists example: owed,partially_paid - name: categoryId in: query schema: type: string format: uuid description: Only invoices in this transaction category - name: linkedEvent in: query schema: type: string format: uuid description: Only invoices linked to this event - name: linkedPolicy in: query schema: type: string format: uuid description: Only invoices linked to this policy - name: linkedPayee in: query schema: type: string format: uuid description: Only invoices with this payee - name: number in: query schema: type: string minLength: 1 description: Only the invoice with this exact invoice number - name: incurredAfter in: query schema: type: string format: date description: Only invoices incurred on or after this date (`YYYY-MM-DD`) - name: incurredBefore in: query schema: type: string format: date description: Only invoices incurred on or before this date (`YYYY-MM-DD`) - name: dueAfter in: query schema: type: string format: date description: Only invoices due on or after this date (`YYYY-MM-DD`) - name: dueBefore in: query schema: type: string format: date description: Only invoices due on or before this date (`YYYY-MM-DD`) - name: unlinked in: query schema: type: boolean description: >- `true` matches invoices with no event and no policy link; `false` applies no filter - name: limit in: query schema: type: integer minimum: 1 maximum: 200 default: 50 description: Page size (default 50, maximum 200) - name: cursor in: query schema: type: string description: >- The previous page's `nextCursor`, echoed verbatim. Opaque — its internals may change shape at any time responses: '200': description: One page of invoices content: application/json: schema: type: object required: - invoices - nextCursor properties: invoices: type: array items: $ref: '#/components/schemas/FinancialsV2Invoice' nextCursor: type: string nullable: true description: >- Cursor for the next page; `null` exactly when the listing is exhausted examples: success: summary: One page with more to fetch value: invoices: - id: 550e8400-e29b-41d4-a716-446655440700 invoiceNumber: INV-389538-455 categoryId: 550e8400-e29b-41d4-a716-446655440100 status: partially_paid linkedEvent: id: 550e8400-e29b-41d4-a716-446655440200 displayName: 'Claim #1042' linkedPolicy: null linkedPayee: id: 550e8400-e29b-41d4-a716-446655440210 entityType: Organization displayName: Smith & Loeb LLP incurredDate: '2026-06-01' dueDate: '2026-07-15' memo: Legal defense fieldData: null lineItems: - lineItemId: 550e8400-e29b-41d4-a716-446655440300 lineItemTypeId: 550e8400-e29b-41d4-a716-446655440110 memo: null amountCents: 10000 totalAmountCents: 10000 amountPaidCents: 4000 balanceDueCents: 6000 paidDate: null lastPaymentDate: '2026-06-10' voidedAt: null deletedAt: null createdAt: '2026-06-01T10:30:00.000Z' updatedAt: '2026-06-10T09:00:00.000Z' headJournalId: 550e8400-e29b-41d4-a716-446655440900 nextCursor: >- eyJ2IjoxLCJ1cGRhdGVkQXQiOiIyMDI2LTA2LTEwVDA5OjAwOjAwLjAwMFoiLCJpZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDcwMCJ9 lastPage: summary: The final page value: invoices: [] nextCursor: null '400': description: >- Bad Request — an unknown query field, a malformed parameter, or an invalid cursor content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unknownQueryField: summary: Unknown query field value: error: code: VALIDATION_ERROR message: 'unexpected: Unrecognized key: "unexpected"' userMessages: - 'unexpected: Unrecognized key: "unexpected"' invalidCursor: summary: Invalid pagination cursor value: error: code: INVALID_CURSOR message: >- The cursor is not a valid pagination cursor for this listing. userMessages: - >- The cursor is not a valid pagination cursor for this listing. '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: >- Not Found — the company does not have this financials surface enabled (the endpoint behaves as if it does not exist) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notFound: summary: Not found value: error: code: NotFoundError message: Not found userMessages: - Not found '500': $ref: '#/components/responses/InternalServerError' components: parameters: companyId: name: companyId in: path required: true schema: type: string format: uuid description: Company identifier schemas: FinancialsV2Invoice: type: object description: >- THE invoice representation — the same shape everywhere an endpoint returns an invoice (listing rows, the detail read, and every write's refreshed-row response). `headJournalId` is the invoice's current journal head — the optimistic-concurrency token subsequent writes echo back as `If-Match`. required: - id - invoiceNumber - categoryId - status - linkedEvent - linkedPolicy - linkedPayee - incurredDate - dueDate - memo - fieldData - lineItems - totalAmountCents - amountPaidCents - balanceDueCents - draftAmountPaidCents - paidDate - lastPaymentDate - voidedAt - deletedAt - approved - approvedAt - createdAt - updatedAt - headJournalId properties: id: type: string format: uuid description: The invoice's id invoiceNumber: type: string description: The invoice's system-minted display number categoryId: type: string format: uuid description: The transaction category the invoice belongs to status: type: string enum: - no_charges - owed - partially_paid - paid - voided - deleted description: >- Derived status, first match wins: `deleted` → `voided` → `no_charges` (every line item's amount is zero) → `paid` (every line item is settled — its amount minus its live marks is exactly zero) → `owed` (no live payment marks) → `partially_paid`. Settlement is per line: no scalar makes a document paid, and a zero-due document with unsettled lines still reads `owed` linkedEvent: type: object nullable: true description: >- The linked event, display-ready (the server resolves the display name), or `null` when not linked to an event required: - id - displayName properties: id: type: string format: uuid description: The linked event's id displayName: type: string description: The linked event's display name linkedPolicy: type: object nullable: true description: >- The linked policy, display-ready, or `null`. An invoice links to an event or a policy, never both required: - id - displayName properties: id: type: string format: uuid description: The linked policy's id displayName: type: string description: The linked policy's display name linkedPayee: type: object nullable: true description: >- The invoice's payee, display-ready, or `null` when none is set. `entityType` is an open string (e.g. `Person`, `Organization`) — the payee vocabulary is the entity module's, not part of this contract required: - id - entityType - displayName properties: id: type: string format: uuid description: The payee entity's id entityType: type: string description: The payee's entity type (e.g. Person, Organization) displayName: type: string description: The payee's display name incurredDate: type: string format: date nullable: true description: The date the charges were incurred (ISO `YYYY-MM-DD`), or `null` dueDate: type: string format: date nullable: true description: When payment is owed (display metadata only), or `null` memo: type: string nullable: true description: Free-text memo, or `null` fieldData: type: object nullable: true additionalProperties: true description: >- Values for the tenant-defined custom invoice fields, keyed by field referenceId — an opaque JSON object, or `null` lineItems: type: array description: The invoice's line items items: $ref: '#/components/schemas/FinancialsV2InvoiceLineItem' totalAmountCents: type: integer description: >- Sum of the ORIENTED line-item amounts (a payable-direction line counts +, a receivable-direction line counts −), in integer cents — the net cash the document commits to move amountPaidCents: type: integer description: >- Sum of the ORIENTED live payment marks, in integer cents — the net cash moved so far balanceDueCents: type: integer description: >- `totalAmountCents - amountPaidCents`, in integer cents — the net cash remaining to move: positive = out, negative = in. May move non-monotonically as opposite-direction lines settle draftAmountPaidCents: type: integer nullable: true description: >- A DRAFT's annex-derived paid total: the oriented net-cash sum of the payment marks the draft was born carrying (the same frame as `amountPaidCents`, which counts LIVE posted marks only and reads 0 while drafting) — what a draft's underlying payment picture will read once finalized. `null` on non-draft invoices (the annex is spent at finalize). Display-only — never a posted ledger amount paidDate: type: string format: date nullable: true description: >- Payment date of the mark that first made every line item settled; clears (`null`) whenever any line reopens lastPaymentDate: type: string format: date nullable: true description: Date of the most recent live payment, or `null` voidedAt: type: string format: date-time nullable: true description: When the invoice was voided, or `null` deletedAt: type: string format: date-time nullable: true description: When the invoice was deleted, or `null` approved: type: boolean description: >- The approval projection: `true` after `invoice.approved`, cleared only by `invoice.unapproved` — an edit never resets approval (the approval-relevant facts, line items and category, are immutable once posted). Only meaningful while the approvals feature is enabled; reads `false` otherwise approvedAt: type: string format: date-time nullable: true description: >- When the approval landed (`invoice.approved`), or `null` while unapproved — `approved` is exactly `approvedAt != null`. Like `approved`, only meaningful while the approvals feature is enabled; reads `null` otherwise createdAt: type: string format: date-time description: When the invoice was created updatedAt: type: string format: date-time description: When the invoice last changed headJournalId: type: string format: uuid description: >- The invoice's current journal head — send it as `If-Match` on the next write to this invoice; a mismatch is a `409` carrying the current row 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 FinancialsV2InvoiceLineItem: type: object description: A stored invoice line item as rendered on invoice reads. required: - lineItemId - lineItemTypeId - memo - amountCents properties: lineItemId: type: string format: uuid description: The line item's id lineItemTypeId: type: string format: uuid description: >- The configured line item type this item cites — discover ids with `GET /api/v1/companies/{companyId}/financials/config/categories` memo: type: string nullable: true description: Free-text memo, or `null` amountCents: type: integer description: >- The line item's amount in integer cents — the magnitude a user would type; a negative amount is a credit within the item's own frame — it posts opposite the line item type's expected direction (e.g. a reversal or refund); the posting rule always comes from the type, never the sign 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. ````