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 - Retrieve paginated list of events with filtering and sorting
• Get Event - Retrieve a single event by ID
• Create Event - Create a new claim or incident
• Update Event - Update an existing event
• Delete Event - Soft delete an event
• 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:

{
  "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:

{
  "insureds": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440200",
      "name": "John Smith",
      "entityType": "individual",
      "email": "[e-mail]",
      "phoneNumber": "[phone]",
      "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).

{
  "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 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

{
  "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 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:

{
  "requestorEmail": "[e-mail]",
  "type": "claim",
  "force": true
}

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.

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

{
  "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
}

---