> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helpgenie.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Lead notes
> Manage notes attached to leads with pinning support and full CRUD operations.
All requests use a single endpoint: `POST https://api.helpgenie.ai/v1` with `resource: "lead-notes"`.
## Access control
All operations require authentication. Access is granted if the user owns the lead (via the lead's agent) or is an internal admin. Non-owners receive a `403 Forbidden` response.
***
## List notes
Retrieves all notes for a specific lead. Pinned notes appear first in the results.
Pinned notes always appear at the top of list results regardless of pagination or creation date. Use the `togglePin` action or set `is_pinned: true` on update to pin important notes so they are never buried.
Must be `"lead-notes"`
Must be `"list"`
The ID of the lead to retrieve notes for.
Number of results to return. Range: 1-500. Default: `50`.
Pagination offset. Default: `0`.
### Response
Array of note objects. See [note object](#note-object).
Total number of notes for this lead.
```typescript Example request theme={null}
const response = await ApiService.invoke<{
notes: LeadNote[];
count: number;
}>({
resource: "lead-notes",
action: "list",
data: {
leadId: 123,
limit: 20,
offset: 0,
},
});
const notes = response?.notes || [];
```
***
## Get a note
Retrieves a specific note by ID.
Must be `"lead-notes"`
Must be `"get"`
The note UUID.
### Response
The note object. See [note object](#note-object).
```typescript Example request theme={null}
const response = await ApiService.invoke<{ note: LeadNote }>({
resource: "lead-notes",
action: "get",
id: "note-uuid-here",
});
```
***
## Create a note
Creates a new note for a lead.
Must be `"lead-notes"`
Must be `"create"`
The ID of the lead to attach this note to.
The note text.
### Response (status 201)
The created note object.
```typescript Example request theme={null}
const response = await ApiService.invoke<{ note: LeadNote }>(
{
resource: "lead-notes",
action: "create",
data: {
leadId: 123,
content: "Follow up next week",
},
},
201
);
const note = response?.note;
```
```bash cURL theme={null}
curl -X POST https://api.helpgenie.ai/v1/lead-notes \
-H "Authorization: Bearer hg_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"resource": "lead-notes",
"action": "create",
"data": {
"leadId": 123,
"content": "Spoke with Jane — interested in the enterprise plan. Schedule a demo for next Tuesday."
}
}'
```
***
## Update a note
Updates an existing note. Only `content` and `is_pinned` fields can be modified.
Must be `"lead-notes"`
Must be `"update"`
The note UUID.
Updated note text.
Whether the note should be pinned.
### Response
The updated note object.
```typescript Example request theme={null}
const response = await ApiService.invoke<{ note: LeadNote }>({
resource: "lead-notes",
action: "update",
id: "note-uuid-here",
data: {
content: "Updated note content",
is_pinned: true,
},
});
```
***
## Delete a note
Permanently deletes a note.
Must be `"lead-notes"`
Must be `"delete"`
The note UUID.
### Response
```typescript Example request theme={null}
const response = await ApiService.invoke<{
success: boolean;
message: string;
}>({
resource: "lead-notes",
action: "delete",
id: "note-uuid-here",
});
```
***
## Toggle pin status
Toggles the pinned status of a note. If the note is pinned it becomes unpinned, and vice versa.
Must be `"lead-notes"`
Must be `"togglePin"`
The note UUID.
### Response
The note object with the updated `is_pinned` value.
```typescript Example request theme={null}
const response = await ApiService.invoke<{ note: LeadNote }>({
resource: "lead-notes",
action: "togglePin",
id: "note-uuid-here",
});
const updatedNote = response?.note;
```
***
## Get pinned notes
Retrieves all pinned notes for a specific lead.
Must be `"lead-notes"`
Must be `"pinned"`
The ID of the lead.
### Response
Array of pinned note objects.
```typescript Example request theme={null}
const response = await ApiService.invoke<{ notes: LeadNote[] }>({
resource: "lead-notes",
action: "pinned",
data: {
leadId: 123,
},
});
const pinnedNotes = response?.notes || [];
```
***
## Note object
UUID of the note.
ID of the lead this note belongs to.
ID of the user who created the note.
The note text.
Whether the note is pinned. Pinned notes sort first in list results.
ISO 8601 timestamp.
ISO 8601 timestamp.
***
## Error responses
| Status | Code | Description |
| ------ | ------------------ | ------------------------------------------- |
| 400 | `VALIDATION_ERROR` | Missing required parameters (e.g. `leadId`) |
| 401 | `UNAUTHORIZED` | Invalid or missing authentication token |
| 403 | `FORBIDDEN` | User does not own the lead |
| 404 | `NOT_FOUND` | Note not found |
| 500 | `INTERNAL_ERROR` | Server error |