> ## 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. # Get Invoice > Returns the whole current invoice document: the invoice, its live payments (newest first), and `headJournalId` — the concurrency token every subsequent write to this invoice sends as `If-Match`. Unlike the listing, the detail read returns **deleted** invoices, so a delete has a confirmable terminal state; `404` is reserved for an unknown id. **Required permission:** `company.payment:read` ## OpenAPI ````yaml /openapi/generated-external-api.yaml get /api/v1/companies/{companyId}/financials/invoices/{invoiceId} 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}: get: tags: - Financials summary: Get Invoice description: > Returns the whole current invoice document: the invoice, its live payments (newest first), and `headJournalId` — the concurrency token every subsequent write to this invoice sends as `If-Match`. Unlike the listing, the detail read returns **deleted** invoices, so a delete has a confirmable terminal state; `404` is reserved for an unknown id. **Required permission:** `company.payment:read` operationId: getFinancialsInvoice parameters: - $ref: '#/components/parameters/companyId' - name: invoiceId in: path required: true schema: type: string format: uuid description: Invoice identifier responses: '200': description: The invoice, its live payments, and the concurrency token content: application/json: schema: type: object required: - invoice - payments - headJournalId properties: invoice: $ref: '#/components/schemas/FinancialsV2Invoice' payments: type: array description: The invoice's live payments, newest first items: $ref: '#/components/schemas/FinancialsV2Payment' headJournalId: type: string format: uuid description: >- The invoice's current journal head — the `If-Match` value for the next write (also carried on the invoice row) examples: success: summary: A partially-paid invoice with one payment value: invoice: 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: null incurredDate: '2026-06-01' dueDate: null 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 payments: - id: 550e8400-e29b-41d4-a716-446655440800 journalId: 550e8400-e29b-41d4-a716-446655440900 lineItemId: 550e8400-e29b-41d4-a716-446655440300 amountCents: 4000 paymentDate: '2026-06-10' erodeReserves: true memo: 'check #100' createdAt: '2026-06-10T09:00:00.000Z' headJournalId: 550e8400-e29b-41d4-a716-446655440900 '400': description: Bad Request — a malformed (non-UUID) invoice id content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: malformedInvoiceId: summary: Malformed invoice id value: error: code: VALIDATION_ERROR message: 'invoiceId: Invalid UUID' userMessages: - 'invoiceId: Invalid UUID' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: >- Not Found — no invoice with this id, or the company does not have this financials surface enabled (indistinguishable by design) 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 '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 FinancialsV2Payment: type: object description: >- A recorded payment MARK on an invoice: one row = one per-line settlement mark against `lineItemId`. `amountCents` is signed in the LINE's frame — its sign matches the line's open remaining, and the mark settles that line toward zero. One journal action per mark (`journalId` is the record that created it), each independently removable by `id`; one gesture (e.g. paying a document's whole balance due) may create several marks. `erodeReserves` is the caller's choice at record time (`null` where the invoice's category has no reserves to erode). required: - id - journalId - lineItemId - amountCents - paymentDate - erodeReserves - memo - createdAt properties: id: type: string format: uuid description: The payment mark's id — the handle for removing it journalId: type: string format: uuid description: The journal record that recorded the mark lineItemId: type: string format: uuid description: The invoice line item the mark settles amountCents: type: integer description: >- The mark's amount in signed integer cents, in its line item's frame — the sign matches the line's remaining and the mark settles it toward zero paymentDate: type: string format: date description: The payment date (ISO `YYYY-MM-DD`) erodeReserves: type: boolean nullable: true description: >- Whether the mark erodes the linked event's reserves; `null` where the invoice's category carries no reserves memo: type: string nullable: true description: Free-text memo, or `null` createdAt: type: string format: date-time description: When the mark was recorded 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. ````