Notes allow you to attach comments and documentation to entities (events, policies, and insureds (exposures)) in AI Insurance. The Notes API supports creating, listing, retrieving, and deleting notes programmatically.
Key Concepts:
- Notes are attached to a specific entity (event, policy, or insured)
- Notes can be privileged (restricted visibility) or standard
- Notes support author override for historical imports and on-behalf-of scenarios
API Endpoints
Author Override
When creating notes via the API, you can specify who the note author should be. This is useful for:
- Historical imports - Migrating notes from legacy systems with original author names
- On-behalf-of creation - Creating notes attributed to a specific user
Author Fields
| Field | Type | Description |
|---|
authorId | string | ID of an existing user in the system. Use when the author has an account. |
authorName | string | Free-text author name. Use for external authors or historical imports. |
authorId and authorName are mutually exclusive. Provide one or the
other, not both.
How Author is Determined
When creating a note:
- If
authorId is provided - The note is linked to that user. The user must exist in the system.
- If
authorName is provided - The name is stored directly (no user lookup). Use for external authors.
- If neither is provided - The note has no specific author assigned.
Response: Author Display
When retrieving notes, the response includes both author (user details) and authorName (display string):
| Response Field | Type | Description |
|---|
author | object or null | User details (id, name, email) if linked to a user, otherwise null |
authorName | string | Display name using fallback: user’s name → stored authorName → “UNKNOWN” |
Always use authorName for display purposes. It provides a consistent display
string regardless of how the author was specified.
Examples
Creating a note with an existing user as author:
{
"requestorEmail": "[email protected]",
"text": "Note created on behalf of another user.",
"authorId": "google-oauth2|123456789"
}
{
"requestorEmail": "[email protected]",
"text": "Historical note imported from legacy system.",
"authorName": "Jane Doe (External)",
"createdAt": "2024-06-15T14:30:00.000Z"
}
{
"id": "550e8400-e29b-41d4-a716-446655440003",
"entityId": "550e8400-e29b-41d4-a716-446655440001",
"entityType": "events",
"text": "Adjuster contacted claimant.",
"author": {
"id": "google-oauth2|123456789",
"name": "John Smith",
"email": "[email protected]"
},
"authorName": "John Smith",
"isPrivileged": false,
"createdAt": "2025-01-15T10:30:00.000Z",
"updatedAt": null
}
{
"id": "550e8400-e29b-41d4-a716-446655440004",
"entityId": "550e8400-e29b-41d4-a716-446655440001",
"entityType": "events",
"text": "Historical note from legacy system.",
"author": null,
"authorName": "Jane Doe (External)",
"isPrivileged": false,
"createdAt": "2024-06-01T14:00:00.000Z",
"updatedAt": null
}
Privileged Notes
Notes can be marked as privileged to restrict their visibility. Privileged notes are only visible to users with the privileged_notes:read permission (typically carrier admins and managers).
Creating a privileged note:
{
"requestorEmail": "[email protected]",
"text": "Internal investigation notes - do not share with claimant.",
"isPrivileged": true
}
To create a privileged note, the requestor must have privileged_notes:read
permission. The API will return an error if the requestor lacks this
permission.
Entity Types
Notes can be attached to three entity types:
| Entity Type | Permission Required | Example Use Case |
|---|
events | claim.notes:read/update | Claim investigation notes, adjuster comments |
policies | policy.notes:read/update | Policy documentation, underwriting notes |
insureds | insured.notes:read/update | Customer communication logs, verification notes |
Pagination and Sorting
List endpoints support pagination and sorting:
| Parameter | Type | Default | Description |
|---|
page | integer | 1 | Page number (1-based) |
sortBy | string | createdAt | Field to sort by (createdAt or updatedAt) |
sortDirection | string | desc | Sort direction (asc or desc) |
items - Array of notes for the current pagetotalCount - Total number of matching notes
