Overview

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

• List Notes - Retrieve notes for an entity
• Create Note - Create a new note
• Get Note - Retrieve a specific note
• Delete Note - Delete a note (soft delete)

---

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:

1. If authorId is provided - The note is linked to that user. The user must exist in the system.
2. If authorName is provided - The name is stored directly (no user lookup). Use for external authors.
3. 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:

{
  "text": "Note created on behalf of another user.",
  "authorId": "google-oauth2|123456789"
}

Creating a note with an external author name:

{
  "text": "Historical note imported from legacy system.",
  "authorName": "Jane Doe (External)",
  "createdAt": "2024-06-15T14:30:00.000Z"
}

Response with linked user:

{
  "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": "[e-mail]"
  },
  "authorName": "John Smith",
  "isPrivileged": false,
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": null
}

Response with external author (no linked user):

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

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

Response includes:

• items - Array of notes for the current page
• totalCount - Total number of matching notes

---