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
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"
]
}
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": "[email protected]",
"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).
{
"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 Company Configuration endpoint. The response includes all custom fields under nonRatingFields.events:
{
"nonRatingFields": {
"events": {
"eventDescription": { "type": "text", "label": "Event Description" },
"claimAmount": { "type": "currency", "label": "Claim Amount" },
"dateOfLoss": { "type": "date", "label": "Date of Loss" }
}
}
}
The Operations API is deprecated and will be replaced with a dedicated endpoint in a future release.
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) |
| Parameter | Type | Default | Description |
|---|
page | integer | 1 | Page number (1-based, page size 50) |
items - Array of events for the current pagetotalCount - Total number of matching events across all pages
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 |
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
}
