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

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](/api-reference/notes/list-notes)** - Retrieve notes for an entity
* **[Create Note](/api-reference/notes/create-note)** - Create a new note
* **[Get Note](/api-reference/notes/get-note)** - Retrieve a specific note
* **[Delete Note](/api-reference/notes/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.    |

<Warning>
  `authorId` and `authorName` are **mutually exclusive**. Provide one or the
  other, not both.
</Warning>

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

<Note>
  Always use `authorName` for display purposes. It provides a consistent display
  string regardless of how the author was specified.
</Note>

### Examples

**Creating a note with an existing user as author:**

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

**Creating a note with an external author name:**

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

**Response with linked user:**

```json theme={null}
{
  "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": "john@example.com"
  },
  "authorName": "John Smith",
  "isPrivileged": false,
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": null
}
```

**Response with external author (no linked user):**

```json theme={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:**

```json theme={null}
{
  "text": "Internal investigation notes - do not share with claimant.",
  "isPrivileged": true
}
```

<Warning>
  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.
</Warning>

***

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

***