> ## 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. # Import Event Financials > Wholesale refresh of one event's financials, in ONE transaction — the import composition: **sweep** (delete every non-deleted invoice currently linked to the event — voided included), then **create** the new slate of invoices (each linked to the path event, optional per-invoice payee), then **set** the expected total per reserved category. An empty request (`invoices: []`, `reserves: []`) clears the event's invoices. **Importing replaces, it does not append.** The request is the full, authoritative set of the event's invoices and reserve expectations. **Idempotency — client-authored ids per action.** Every create and every reserve set carries its own client-minted `actionId` (all unique in one request); sweep deletes mint their own. The composition commits atomically, so ANY of your ids already journaled proves the whole prior run committed: the retry short-circuits to your ids plus refreshed read state, re-applying nothing. A mix of journaled and fresh ids is `409 ACTION_ID_REUSED` (ids reused across different runs). **No `If-Match`** — the composition locks every touched aggregate. Member-action preconditions surface as `422` with the standard stable codes (e.g. `UNKNOWN_ID`, `DEPRECATED_CONFIG`, `NOT_RESERVED_CATEGORY`, `FUTURE_DATE`, `LINK_TARGET_MISSING`); preconditions fail closed — the whole import rolls back. An expected total is UNCONSTRAINED: the composed `reserves.set` may land a scope's expected total below its paid-to-date — a legal state whose remaining reserve reads negative (see [Set Reserves](/api-reference/financials/set-reserves)). **Attachments are sidecar** — upload documents through the platform files API; this endpoint takes none. **Required permission:** `company.payment:update` ## OpenAPI ````yaml /openapi/generated-external-api.yaml post /api/v1/companies/{companyId}/financials/events/{eventId}/import 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/events/{eventId}/import: post: tags: - Financials summary: Import Event Financials description: > Wholesale refresh of one event's financials, in ONE transaction — the import composition: **sweep** (delete every non-deleted invoice currently linked to the event — voided included), then **create** the new slate of invoices (each linked to the path event, optional per-invoice payee), then **set** the expected total per reserved category. An empty request (`invoices: []`, `reserves: []`) clears the event's invoices. **Importing replaces, it does not append.** The request is the full, authoritative set of the event's invoices and reserve expectations. **Idempotency — client-authored ids per action.** Every create and every reserve set carries its own client-minted `actionId` (all unique in one request); sweep deletes mint their own. The composition commits atomically, so ANY of your ids already journaled proves the whole prior run committed: the retry short-circuits to your ids plus refreshed read state, re-applying nothing. A mix of journaled and fresh ids is `409 ACTION_ID_REUSED` (ids reused across different runs). **No `If-Match`** — the composition locks every touched aggregate. Member-action preconditions surface as `422` with the standard stable codes (e.g. `UNKNOWN_ID`, `DEPRECATED_CONFIG`, `NOT_RESERVED_CATEGORY`, `FUTURE_DATE`, `LINK_TARGET_MISSING`); preconditions fail closed — the whole import rolls back. An expected total is UNCONSTRAINED: the composed `reserves.set` may land a scope's expected total below its paid-to-date — a legal state whose remaining reserve reads negative (see [Set Reserves](/api-reference/financials/set-reserves)). **Attachments are sidecar** — upload documents through the platform files API; this endpoint takes none. **Required permission:** `company.payment:update` operationId: importFinancialsEvent parameters: - $ref: '#/components/parameters/companyId' - name: eventId in: path required: true schema: type: string format: uuid description: Event identifier — an unknown event is `404` requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - invoices - reserves properties: invoices: type: array description: >- The event's new invoice slate, created in order — each linked to the path event items: type: object additionalProperties: false required: - actionId - categoryId - lineItems properties: actionId: type: string format: uuid description: >- Client-minted id for THIS create — becomes its journal id; unique within the request categoryId: type: string format: uuid description: The invoice's transaction category incurredDate: type: string format: date description: >- The date the charges were incurred (ISO `YYYY-MM-DD`); must not be in the future dueDate: type: string format: date description: When payment is owed — display metadata only memo: type: string description: Free-text memo fieldData: type: object additionalProperties: true description: >- Values for the tenant-defined custom invoice fields, keyed by field referenceId lineItems: type: array items: $ref: '#/components/schemas/FinancialsV2WriteLineItem' payee: type: string format: uuid description: The invoice's payee entity (optional) reserves: type: array description: >- The expected total per reserved category — at most one entry per category items: type: object additionalProperties: false required: - actionId - categoryId - expectedTotalCents - reserveDate properties: actionId: type: string format: uuid description: >- Client-minted id for THIS reserve set — becomes its journal id; unique within the request categoryId: type: string format: uuid description: A configured RESERVED transaction category expectedTotalCents: type: integer description: >- The scope's new ABSOLUTE expected total, in user display cents. Unconstrained — a value below the scope's paid-to-date is legal and leaves the remaining reserve negative reserveDate: type: string format: date description: >- The reserve date (ISO `YYYY-MM-DD`); must not be in the future memo: type: string description: Free-text memo author: type: string minLength: 1 maxLength: 255 description: >- Optional display label for the source system's author (e.g. the integrator-side user). Stamped as the journal record's display attribution; the acting principal stays the External API service user, so a label can never impersonate an in-app user. Ignored on idempotent replays examples: fullImport: summary: One invoice plus one reserve expectation value: invoices: - actionId: 3a5b7c9d-1e2f-4a4b-6c8d-7e9f0a1b2c3d categoryId: 550e8400-e29b-41d4-a716-446655440101 incurredDate: '2026-06-01' memo: Imported loss lineItems: - lineItemId: 550e8400-e29b-41d4-a716-446655440301 lineItemTypeId: 550e8400-e29b-41d4-a716-446655440111 amountCents: 250000 payee: 550e8400-e29b-41d4-a716-446655440210 reserves: - actionId: 4b6c8d0e-2f3a-4b5c-7d9e-8f0a1b2c3d4e categoryId: 550e8400-e29b-41d4-a716-446655440101 expectedTotalCents: 1200000 reserveDate: '2026-06-01' clearEvent: summary: Clear the event's invoices (sweep only) value: invoices: [] reserves: [] responses: '200': description: >- A fresh run returns EVERY emitted journal id in execution order (sweep — companions included — then creates, then sets); a short-circuited retry returns the client-authored ids. Either way: the created invoices' current rows and each set scope's refreshed expected total content: application/json: schema: type: object required: - journalIds - invoices - reserves properties: journalIds: type: array items: type: string format: uuid description: >- Every emitted journal id in execution order (client-authored ids only, on a replayed retry) invoices: type: array description: The created invoices' current rows, in request order items: $ref: '#/components/schemas/FinancialsV2Invoice' reserves: type: array description: Each set scope's refreshed expected total items: type: object required: - categoryId - expectedTotalCents properties: categoryId: type: string format: uuid expectedTotalCents: type: integer description: >- The scope's expected total after the import, in user display cents examples: imported: summary: >- Import committed (sweep of one prior invoice, one create, one set) value: journalIds: - 5c7d9e1f-3a4b-4c6d-8e0f-9a1b2c3d4e5f - 3a5b7c9d-1e2f-4a4b-6c8d-7e9f0a1b2c3d - 4b6c8d0e-2f3a-4b5c-7d9e-8f0a1b2c3d4e invoices: - id: 550e8400-e29b-41d4-a716-446655440701 invoiceNumber: INV-441202-118 categoryId: 550e8400-e29b-41d4-a716-446655440101 status: owed 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: null memo: Imported loss fieldData: null lineItems: - lineItemId: 550e8400-e29b-41d4-a716-446655440301 lineItemTypeId: 550e8400-e29b-41d4-a716-446655440111 memo: null amountCents: 250000 totalAmountCents: 250000 amountPaidCents: 0 balanceDueCents: 250000 paidDate: null lastPaymentDate: null voidedAt: null deletedAt: null createdAt: '2026-06-01T10:30:00.000Z' updatedAt: '2026-06-01T10:30:00.000Z' headJournalId: 3a5b7c9d-1e2f-4a4b-6c8d-7e9f0a1b2c3d reserves: - categoryId: 550e8400-e29b-41d4-a716-446655440101 expectedTotalCents: 1200000 '400': description: >- Bad Request — a malformed payload, duplicate `actionId`s, or a category named twice in `reserves` content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: duplicateActionIds: summary: Duplicate actionIds in one import value: error: code: VALIDATION_ERROR message: 'invoices: every actionId in an import must be unique' userMessages: - 'invoices: every actionId in an import must be unique' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: >- Not Found — no event 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: eventNotFound: summary: Event not found value: error: code: NotFoundError message: Event not found userMessages: - Event not found '409': $ref: '#/components/responses/FinancialsV2ActionIdReused' '422': $ref: '#/components/responses/FinancialsV2PreconditionFailed' '500': $ref: '#/components/responses/InternalServerError' components: parameters: companyId: name: companyId in: path required: true schema: type: string format: uuid description: Company identifier schemas: FinancialsV2WriteLineItem: type: object description: >- One line item of an invoice write. `lineItemId` is caller-minted and stable across updates — payment marks target it. Amounts are integer cents; direction never rides the sign: `amountCents` is the magnitude a user would type, and 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. required: - lineItemId - lineItemTypeId - amountCents properties: lineItemId: type: string format: uuid description: >- Caller-minted id for the line item — keep it stable across updates to preserve the item's identity (payment marks reference it) lineItemTypeId: type: string format: uuid description: >- A configured line item type OF THE CITED CATEGORY — discover ids with `GET /api/v1/companies/{companyId}/financials/config/categories`. A type outside the invoice's category is `422 UNKNOWN_ID` memo: type: string description: Free-text memo amountCents: type: integer description: >- The line item's amount in integer cents — the user-typed magnitude; negative = a credit within the item's frame, posting opposite the type's expected direction 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 FinancialsV2PreconditionError: type: object description: >- A failed write precondition (`422`): the request was well-formed but the books reject it. Preconditions fail closed — a rejected write leaves no journal record, no ledger change, and no read-state change. `error.code` is one of the STABLE financials error codes (single source: `FINANCIALS_V2_PRECONDITION_CODES` in the engine's error module, re-exported to this surface as `FINANCIALS_V2_API_ERROR_CODES`) — messages may be reworded, the codes will not. required: - error properties: error: type: object required: - code - message properties: code: type: string enum: - LIVE_PAYMENTS - AMOUNT_EXCEEDS_BALANCE_DUE - INVALID_AMOUNT - LINE_ITEMS_IMMUTABLE - INVOICE_DELETED - INVOICE_VOIDED - INVOICE_DRAFT - INVOICE_NOT_DRAFT - PAYMENT_NOT_FOUND - ERODE_RESERVES_MISMATCH - ERODE_REQUIRES_EVENT - DEPRECATED_CONFIG - NOT_RESERVED_CATEGORY - FUTURE_DATE - UNKNOWN_ID - LINK_TARGET_MISSING - UNAPPROVE_PAID - NOT_APPROVED - POLICY_INVOICE_BATCH_ONLY description: >- The stable precondition code — one per guard. `LIVE_PAYMENTS` (the action — re-link, payee change, or void — needs the invoice's live payments removed first); `AMOUNT_EXCEEDS_BALANCE_DUE` (a payment mark's magnitude overshoots its line item's remaining — per line, never a document scalar); `INVALID_AMOUNT` (a zero mark, or a mark whose sign opposes its line item's open remaining — a `payBalanceDue` against a document with nothing open included); `LINE_ITEMS_IMMUTABLE` (a posted invoice's line items — ids, types, amounts — and its category are fixed from the posting moment: any post-posting change is rejected, at any payment count; corrections are void-and-recreate, payments removed first; drafts edit freely until finalize); `INVOICE_DELETED` / `INVOICE_VOIDED` (lifecycle closures); `INVOICE_DRAFT` (drafts are unposted — money may not touch one: recording a payment on or voiding a draft is rejected; finalize it first); `INVOICE_NOT_DRAFT` (finalize targets exactly a draft); `PAYMENT_NOT_FOUND` (no live payment mark with that id on that invoice); `ERODE_RESERVES_MISMATCH` / `ERODE_REQUIRES_EVENT` (the erode flag missing on a reserved category or present on operating; eroding needs a linked event — there is no headroom bound: the remaining reserve is a signed balance and may cross zero); `DEPRECATED_CONFIG` / `NOT_RESERVED_CATEGORY` / `UNKNOWN_ID` (cited configuration guards); `FUTURE_DATE`; `LINK_TARGET_MISSING` (the named link target does not exist); `UNAPPROVE_PAID` (an approval cannot be revoked once payments have been recorded — remove them first); `NOT_APPROVED` (money cannot post against an unapproved invoice AND the calling key does not hold `company.payment:approve`, so it cannot approve it either — a key that holds the permission auto-approves instead of failing here); `POLICY_INVOICE_BATCH_ONLY` (the write touches a POLICY-LINKED invoice's document — creating one with `links.policy`, or updating, voiding, restoring, deleting, or re-linking one that is already policy-linked. A policy's invoices are issued as one set so that every price component of the policy's pricing contract stays netted to its own line item, so they are written only by the policy invoice batch: `POST /api/v1/companies/{companyId}/financials/policies/{policyId}/invoices/batch`. Change the policy or submit an explicit batch and the invoices are reissued. Payments, payee changes, and approvals on a policy invoice are unaffected) message: type: string description: Human-readable description of the failed precondition userMessages: type: array description: Clean, verbatim-displayable messages items: type: string 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 FinancialsV2ActionIdReused: description: >- Conflict — the `actionId` was already used by a DIFFERENT action (different action type, target, or client payload). Supply a fresh uuid. An IDENTICAL retry never conflicts: it replays the original outcome (`200`) instead. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: actionIdReused: summary: actionId reused by a different action value: error: code: ACTION_ID_REUSED message: >- actionId 550e8400-e29b-41d4-a716-446655440000 was already used by a different action; supply a fresh uuid (or retry with the identical action to replay it) userMessages: - >- actionId 550e8400-e29b-41d4-a716-446655440000 was already used by a different action; supply a fresh uuid (or retry with the identical action to replay it) FinancialsV2PreconditionFailed: description: >- Unprocessable — a write precondition failed. Fails closed: no journal record, no ledger change, no read-state change. `error.code` is one of the stable financials error codes; each operation's description names its signature codes. content: application/json: schema: $ref: '#/components/schemas/FinancialsV2PreconditionError' examples: livePayments: summary: The action requires the invoice's live payments removed first value: error: code: LIVE_PAYMENTS message: >- The invoice has live payments; remove them before this action userMessages: - >- The invoice has live payments; remove them before this action unknownId: summary: >- A cited configuration id is unknown (or outside the cited category) value: error: code: UNKNOWN_ID message: lineItemTypeId does not belong to the cited category userMessages: - lineItemTypeId does not belong to the cited category policyInvoiceBatchOnly: summary: >- Policy-linked invoice documents are changed only as one policy batch value: error: code: POLICY_INVOICE_BATCH_ONLY message: >- Policy-linked invoice documents can only be changed through POST /api/v1/companies/{companyId}/financials/policies/{policyId}/invoices/batch userMessages: - >- Policy-linked invoice documents can only be changed through POST /api/v1/companies/{companyId}/financials/policies/{policyId}/invoices/batch 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. ````