> ## Documentation Index
> Fetch the complete documentation index at: https://docs.frankieone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Comments

Learn how to add, retrieve, and manage comments on entity profiles for a complete audit trail.

## What are Comments?

The Comments feature allows your operators and integrated systems to programmatically add notes and observations directly to an entity's profile (both Individuals and Organisations). This functionality is essential for maintaining a comprehensive and contextual audit trail.

Every comment is timestamped and associated with the user or API key that created it, providing crucial context for compliance reviews, manual investigations, and decision-making processes.

## How It Works

The process for adding a comment is straightforward and involves a single API call.

<Steps>
  <Step title="1. Identify the Entity">
    Determine the `entityId` of the Individual or Organisation you wish to add a comment to.
  </Step>

  <Step title="2. Call the Comments Endpoint">
    Make a `POST` request to the `/v2/comments` endpoint, providing the `entityId` and the text of your comment in the request body.
  </Step>

  <Step title="3. Comment is Recorded">
    FrankieOne saves the comment, linking it to the specified entity profile and recording the author and timestamp.
  </Step>

  <Step title="4. View the Comment">
    The comment is now visible in the entity's activity history within the FrankieOne Portal and can be retrieved via the API.
  </Step>
</Steps>

***

## API Integration Guide

### Add a Comment to an Entity

To add a comment, make a `POST` request to the `/v2/comments` endpoint.

#### Request Body

The request body must contain the ID of the entity and the content of the comment.

| Field      | Type   | Required | Description                                  |
| ---------- | ------ | -------- | -------------------------------------------- |
| `entityId` | String | Yes      | The unique identifier for the entity.        |
| `comment`  | String | Yes      | The text content of the comment to be added. |

**Example Request**

```json theme={null}
{
  "entityId": "ind-0b6110e0-c167-4e69-92b0-9d3b7a5e9f7a",
  "comment": "Operator Jane Doe confirmed source of funds via phone call on Oct 15, 2025. Follow-up required in 30 days."
}
```

#### Response Body

A successful request will return a `201 Created` status code and the full comment object, including its unique `commentId` and server-generated metadata.

**Example Response**

```json theme={null}
{
  "commentId": "cmt-a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "entityId": "ind-0b6110e0-c167-4e69-92b0-9d3b7a5e9f7a",
  "comment": "Operator Jane Doe confirmed source of funds via phone call on Oct 15, 2025. Follow-up required in 30 days.",
  "createdAt": "2025-10-15T07:10:00.000Z",
  "authorId": "user-a4b2c89-1234-5678-90ab-cdef12345678",
  "authorDisplayName": "Jane Doe"
}
```

<Callout icon="thumbtack" color="#1A6CFF" iconType="regular">
  The `authorId` and `authorDisplayName` are automatically determined from the authentication context (API Key or user session) of the request.
</Callout>

***

## Common Use Cases

Adding comments via the API is useful for a variety of scenarios:

* **Documenting Manual Actions:** Record notes from offline actions, such as phone calls or in-person meetings.
* **Explaining Overrides:** Provide justification when a compliance officer manually overrides a workflow decision or an automated check result.
* **Integrating External System Data:** Push alerts or notes from third-party case management or fraud systems into the FrankieOne entity profile.
* **Case Management:** Allow operators to add notes and updates as they investigate a case, creating a running log of their findings.