> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiinsurance.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

The Event Financials API allows you to manage financial transactions and reserves for events (claims and incidents). This includes creating payments, tracking reserves, and viewing financial totals across events.

**Key Concepts:**

* **Transactions**: Financial records associated with events (payments, invoices)
* **Reserves**: Expected costs set aside for future payments
* **Transaction Types**: Categories like `indemnity_invoice` (loss payments) and `alae_invoice` (allocated loss adjustment expenses)
* **Amounts in cents**: Most endpoints return amounts in cents (multiply by 100 from dollars)

***

## API Endpoints

### Transaction Management

* **[List Event Transactions](/api-reference/event-financials/list-event-transactions)** - Get paginated list of transactions for an event
* **[Get Event Transaction](/api-reference/event-financials/get-event-transaction)** - Get a single transaction with line items
* **[Create Event Transaction](/api-reference/event-financials/create-event-transaction)** - Create a new payment or invoice
* **[Void Event Transaction](/api-reference/event-financials/void-event-transaction)** - Void an existing transaction
* **[Get Event Transaction Totals](/api-reference/event-financials/get-event-transaction-totals)** - Get transaction totals by category for an event

### Reserves & Totals

* **[Get Event Reserves](/api-reference/event-financials/get-event-reserves)** - Get reserve amounts by category for an event
* **[Update Expected Totals](/api-reference/event-financials/update-expected-totals)** - Update expected total (reserves) for a category
* **[List Expected Total Timeline](/api-reference/event-financials/list-expected-total-timeline)** - Get chronological timeline of reserve changes
* **[List Financial Totals](/api-reference/event-financials/list-event-financial-totals)** - Get financial totals across all events by transaction type

***

## Transaction Types

Transaction types are configurable per company. Common built-in types include:

| Type                | Description                        |
| ------------------- | ---------------------------------- |
| `indemnity_invoice` | Loss payments (indemnity)          |
| `alae_invoice`      | Allocated Loss Adjustment Expenses |

Use the [GET /transaction-categories](/api-reference/transaction-categories/list-transaction-categories) endpoint to see all available transaction types for your company.

### Itemized vs Non-Itemized

Transaction types can be either:

* **Non-itemized**: Single amount per transaction (e.g., `indemnity_invoice`)
* **Itemized**: Multiple line items per transaction (e.g., `alae_invoice`)

When creating transactions, use the appropriate field:

* Non-itemized: `amount` field (required), `lineItems` forbidden
* Itemized: `lineItems` array (required), `amount` forbidden

***

## Transaction Status

| Status     | Description                              |
| ---------- | ---------------------------------------- |
| `owed`     | Payment is pending/due                   |
| `paid`     | Payment has been made                    |
| `approved` | Transaction is approved but not yet paid |
| `void`     | Transaction has been voided              |

***

## Amount Conventions

**Important:** Different endpoints use different units:

| Endpoint                  | Unit        |
| ------------------------- | ----------- |
| GET transactions          | Cents       |
| GET reserves              | Cents       |
| GET totals                | Cents       |
| POST transactions         | Cents       |
| **PATCH expected-totals** | **Dollars** |

The PATCH expected-totals endpoint uses dollars for historical compatibility.

***

## Reserves vs Expected Totals

* **Expected Total**: The anticipated total cost for a category (set by user/adjuster)
* **Reserves**: Calculated as `expectedTotal - paid - owed`
* **Owed**: Total amount of pending transactions
* **Paid**: Total amount of completed transactions

Example:

```
Expected Total: $15,000
Paid:           $5,000
Owed:           $2,000
Reserves:       $8,000 (15000 - 5000 - 2000)
```

***

## Permissions

| Operation                    | Permission                                         |
| ---------------------------- | -------------------------------------------------- |
| List/Get Transactions        | `company.event:export`                             |
| Create Transactions          | `company.payment:create`                           |
| Void Transaction             | `company.payment:update`                           |
| Get Transaction Totals       | `company.payment:read`                             |
| Get Reserves                 | `company.payment:read`                             |
| Update Expected Totals       | `company.claim:update` / `company.incident:update` |
| List Expected Total Timeline | `company.payment:read`                             |
| List Financial Totals        | `company.payment:read`                             |

***

## Example: Creating a Payment

```json theme={null}
// POST /events/{eventId}/financials/transactions
{
  "transactionType": "indemnity_invoice",
  "transactionDate": "2025-01-15",
  "amount": 500000,
  "payeeId": "550e8400-e29b-41d4-a716-446655440050",
  "description": "Initial claim payment",
  "status": "paid",
  "paidDate": "2025-01-20"
}
```

Response:

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440010"
}
```

***

## Example: Voiding a Transaction

```json theme={null}
// PATCH /events/{eventId}/financials/transactions/{transactionId}
{
  "status": "void",
  "voidReason": "Duplicate invoice"
}
```

Response returns the full transaction detail with `status: "void"` and the provided `voidReason`.

***

## Example: Updating Reserves

```json theme={null}
// PATCH /events/{eventId}/financials/expected-totals
{
  "type": "claim",
  "categoryId": "indemnity_invoice",
  "expectedTotal": 15000
}
```

Response:

```json theme={null}
{
  "eventId": "550e8400-e29b-41d4-a716-446655440001",
  "categoryId": "indemnity_invoice",
  "expectedTotal": 15000,
  "reserves": 10000
}
```

<Note>
  The `type` field (claim/incident) is required for permission resolution. The event type must match the value provided.
</Note>

***

## Nullable Fields

| Field           | When null                            |
| --------------- | ------------------------------------ |
| `payeeId`       | No payee associated with transaction |
| `invoiceNumber` | No invoice number assigned           |
| `invoiceDate`   | No invoice date set                  |
| `dueDate`       | No due date set                      |
| `paidDate`      | Transaction is not paid              |
| `description`   | No description provided              |
| `voidReason`    | Transaction is not voided            |
| `reserves`      | Category doesn't support reserves    |
| `updatedAt`     | Transaction has never been updated   |