> ## 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

Events represent claims and incidents in AI Insurance. The Events API allows you to programmatically create, read, update, and delete event information, including custom entity data specific to your company's configuration.

**Key Concepts:**

* Events come in two types: **claims** and **incidents**
* Events can have **open** or **closed** status
* Events must have one or more **insureds** (required)
* Events can optionally be associated with a **policy**
* Events contain **custom entity data** (`data` field) with field keys mapped to values

***

## API Endpoints

* **[List Events](/api-reference/events/list-events)** - Retrieve paginated list of events with filtering and sorting
* **[Get Event](/api-reference/events/get-event)** - Retrieve a single event by ID
* **[Create Event](/api-reference/events/create-event)** - Create a new claim or incident
* **[Update Event](/api-reference/events/update-event)** - Update an existing event
* **[Delete Event](/api-reference/events/delete-event)** - Soft delete an event
* **[Get Events Configuration](/api-reference/events/get-events-configuration)** - Retrieve JSON Schema for event custom fields

***

## Event Types

Events can be one of two types:

| Type       | Description                                     |
| ---------- | ----------------------------------------------- |
| `claim`    | Insurance claim filed against a policy          |
| `incident` | Incident or occurrence that may lead to a claim |

***

## Event Status

Events can have one of two statuses:

| Status   | Description                         |
| -------- | ----------------------------------- |
| `open`   | Event is active and being processed |
| `closed` | Event has been resolved and closed  |

***

## Associated Insureds

Events are associated with one or more insureds via the `insuredIds` field.

By default, the API returns an array of insured IDs:

```json theme={null}
{
  "insuredIds": [
    "550e8400-e29b-41d4-a716-446655440200",
    "550e8400-e29b-41d4-a716-446655440201"
  ]
}
```

When using `GET /events/{eventId}`, you can request expanded insured details with `expand=insureds`:

```json theme={null}
{
  "insureds": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440200",
      "name": "John Smith",
      "entityType": "individual",
      "email": "john.smith@example.com",
      "phoneNumber": "+1-555-123-4567",
      "billingEmail": null
    }
  ]
}
```

***

## Custom Entity Data

The `data` field contains custom entity data specific to each company's configuration. This allows you to store and retrieve company-specific information about events.

### Field Keys vs Field IDs

**Important:** The `data` field uses **field keys** (human-readable names like "eventDescription") instead of field IDs (UUIDs).

```json theme={null}
{
  "data": {
    "eventDescription": "Vehicle accident at intersection",
    "claimAmount": "50000",
    "adjusterId": "ADJ-12345"
  }
}
```

### When is `data` null?

The `data` field returns:

* **`null`** - When no custom entity data exists for the event
* **`{ ... }`** - An object with field key-value pairs when custom data exists

### Field Configuration

Custom entity data fields are configured per company in AI Insurance. The available fields and their keys depend on your company's setup.

To see which fields are available for events, use the [Get Events Configuration](/api-reference/events/get-events-configuration) endpoint. The response includes:

* **`data`** — a standard JSON Schema (draft 2020-12) describing all possible fields
* **`fieldCoverageTypeMappings`** — maps each field key to `"all"` (applies to all events) or an array of coverage type IDs
* **`companyCoverageTypes`** — the list of coverage types enabled for your company

```json theme={null}
{
  "data": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "eventDescription": {
        "type": "string",
        "title": "Event Description"
      },
      "claimAmount": {
        "type": "number",
        "title": "Claim Amount",
        "format": "currency"
      },
      "adjusterId": {
        "type": "string",
        "title": "Adjuster ID"
      }
    }
  },
  "fieldCoverageTypeMappings": {
    "eventDescription": "all",
    "claimAmount": "all",
    "adjusterId": ["general_liability", "workers_comp"]
  },
  "companyCoverageTypes": ["general_liability", "workers_comp", "auto"]
}
```

A field mapped to `"all"` applies to every event. A field mapped to an array of coverage type IDs only applies to events of those coverage types. If a field's coverage type list matches every ID in `companyCoverageTypes`, it effectively applies to all events today — but won't automatically extend to new coverage types added in the future.

See [JSON Schema Format Types](/api-legacy-reference/data-models#json-schema-format-types) for the list of supported `format` values.

***

## Nullable Fields

The following fields may be `null` in the response:

| Field       | When null                                  |
| ----------- | ------------------------------------------ |
| `policyId`  | Event is not associated with a policy      |
| `createdBy` | Creator was not tracked                    |
| `updatedAt` | Event has never been updated               |
| `data`      | No custom entity data exists for the event |

***

## Filtering and Sorting

List endpoints support comprehensive filtering and sorting options:

### Filter Parameters

| Parameter    | Type            | Description                                |
| ------------ | --------------- | ------------------------------------------ |
| `type`       | string or array | Filter by event type (`claim`, `incident`) |
| `status`     | string or array | Filter by status (`open`, `closed`)        |
| `policyId`   | string          | Filter by associated policy ID (UUID)      |
| `filterText` | string          | Text search across event fields            |

### Sorting Parameters

| Parameter       | Type   | Default     | Description                                                |
| --------------- | ------ | ----------- | ---------------------------------------------------------- |
| `sortBy`        | string | `createdAt` | Field to sort by (`createdAt`, `updatedAt`, `referenceId`) |
| `sortDirection` | string | `desc`      | Sort direction (`asc` or `desc`)                           |

### Pagination

| Parameter | Type    | Default | Description                         |
| --------- | ------- | ------- | ----------------------------------- |
| `page`    | integer | 1       | Page number (1-based, page size 50) |

**Response includes:**

* `items` - Array of events for the current page
* `totalCount` - Total number of matching events across all pages

***

## Deleting Events with Financial Transactions

By default, events with **paid** or **processing** financial transactions cannot be deleted. This protects financial data integrity.

If you need to delete such an event, you can set `force: true` in the DELETE request body:

```json theme={null}
{
  "requestorEmail": "user@example.com",
  "type": "claim",
  "force": true
}
```

<Warning>
  **Use `force: true` with caution.** Force deleting an event with financial transactions will **orphan** those financial records. The transactions will remain in the system but will no longer be linked to an event. This action cannot be undone.
</Warning>

If you attempt to delete an event with financial transactions without `force: true`, the API will return an error message indicating how many transactions are blocking deletion.

***

## Permissions

Access to events requires the appropriate permissions based on your API key. Permissions are event-type specific:

| Operation         | Claims Permission      | Incidents Permission      |
| ----------------- | ---------------------- | ------------------------- |
| List Events       | `company.claim:read`   | `company.incident:read`   |
| Get Event         | `company.claim:read`   | `company.incident:read`   |
| Create Event      | `company.claim:create` | `company.incident:create` |
| Update Event      | `claim:update`         | `incident:update`         |
| Delete Event      | `company.claim:delete` | `company.incident:delete` |
| Get Configuration | `company.event:read`   | `company.event:read`      |

**Note:** Update permissions use a slightly different format (`claim:update` vs `company.claim:update`).

***

## Example Response

```json theme={null}
{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "companyId": "550e8400-e29b-41d4-a716-446655440000",
      "type": "claim",
      "status": "open",
      "referenceId": "CLM-2025-001",
      "coverageTypeId": "general_liability",
      "policyId": "550e8400-e29b-41d4-a716-446655440100",
      "insuredIds": [
        "550e8400-e29b-41d4-a716-446655440200",
        "550e8400-e29b-41d4-a716-446655440201"
      ],
      "createdAt": "2025-01-15T10:30:00.000Z",
      "createdBy": "google-oauth2|123456789",
      "updatedAt": "2025-01-16T14:20:00.000Z",
      "data": {
        "eventDescription": "Vehicle accident at intersection",
        "claimAmount": "50000",
        "dateOfLoss": "2025-01-10"
      }
    }
  ],
  "totalCount": 42
}
```

***