---
title: Notes
description: Read, add, edit and delete notes on prospect contacts.
product: signal
section: api
order: 20
---

# Notes

Notes are free-text entries on a [prospect contact](prospects.md), shown on the prospect contact's page in Signal. A prospect contact can have any number of notes.

You can also add a note while creating or updating a prospect contact by sending `notes` to [`POST /prospects`](prospects.md#create-or-update-a-prospect-contact) or [`PATCH /prospects/{id}`](prospects.md#update-a-prospect-contact).

## The note object

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string | 25-character ID. |
| `prospect_id` | string | The prospect contact the note is on. |
| `content` | string | |
| `created_by` | string or null | User ID of the author. `null` when the note was added through the API without an author. |
| `created_at` | string | ISO 8601 timestamp. |
| `updated_at` | string | ISO 8601 timestamp. |

```json
{
  "id": "cm3ka2b7t0005ab7cx1y2z3w4",
  "prospect_id": "e4b7c1d9-2f6a-4b3e-9c8d-5a1f7e2b4c63",
  "content": "Requested a demo from the pricing page.",
  "created_by": null,
  "created_at": "2026-11-12T09:30:00.000Z",
  "updated_at": "2026-11-12T09:30:00.000Z"
}
```

---

## List notes

`GET /notes` · Scope: `notes:read`

Returns notes newest first.

### Query parameters

| Parameter | Type | Required | Notes |
| --- | --- | --- | --- |
| `prospect_id` | string | No | Only notes on this prospect contact. |
| `limit` | integer | No | 1 to 100. Default 20. |
| `cursor` | string | No | `meta.cursor` from the previous page. |

### Example

```bash
curl "https://crm.empiraa.app/api/v1/notes?prospect_id=e4b7c1d9-2f6a-4b3e-9c8d-5a1f7e2b4c63" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```js
const url = new URL("https://crm.empiraa.app/api/v1/notes");
url.searchParams.set("prospect_id", "e4b7c1d9-2f6a-4b3e-9c8d-5a1f7e2b4c63");
const res = await fetch(url, { headers: { Authorization: "Bearer YOUR_API_KEY" } });
```

### Response `200`

An array of [note objects](#the-note-object) in `data`; `meta` has `cursor` and `hasMore`.

---

## Add a note

`POST /notes` · Scope: `notes:write`

### Request body

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `prospect_id` | string | Yes | A prospect contact in this workspace. |
| `content` | string | Yes | |
| `created_by` | string or null | No | User ID to credit as the author: an active member of the workspace, or `404 NOT_FOUND`. |

### Example

```bash
curl -X POST https://crm.empiraa.app/api/v1/notes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prospect_id": "e4b7c1d9-2f6a-4b3e-9c8d-5a1f7e2b4c63", "content": "Asked for a case study in logistics."}'
```

```js
await fetch("https://crm.empiraa.app/api/v1/notes", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    prospect_id: "e4b7c1d9-2f6a-4b3e-9c8d-5a1f7e2b4c63",
    content: "Asked for a case study in logistics.",
  }),
});
```

### Response `201`

The new [note object](#the-note-object) in `data`.

### Errors

| Status | Code | When |
| --- | --- | --- |
| 400 | `INVALID_REQUEST` | `prospect_id` or `content` is missing. |
| 404 | `NOT_FOUND` | No prospect contact with that ID in this workspace, or `created_by` isn't an active member of it. |

**Webhook events:** none.

---

## Get a note

`GET /notes/{id}` · Scope: `notes:read`

### Example

```bash
curl https://crm.empiraa.app/api/v1/notes/cm3ka2b7t0005ab7cx1y2z3w4 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```js
await fetch("https://crm.empiraa.app/api/v1/notes/cm3ka2b7t0005ab7cx1y2z3w4", {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});
```

### Response `200`

The [note object](#the-note-object) in `data`.

### Errors

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No note with that ID in this workspace. |

---

## Edit a note

`PATCH /notes/{id}` · Scope: `notes:write`

### Request body

| Field | Type | Notes |
| --- | --- | --- |
| `content` | string | The new text. |

### Example

```bash
curl -X PATCH https://crm.empiraa.app/api/v1/notes/cm3ka2b7t0005ab7cx1y2z3w4 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Asked for a case study in cold-chain logistics."}'
```

```js
await fetch("https://crm.empiraa.app/api/v1/notes/cm3ka2b7t0005ab7cx1y2z3w4", {
  method: "PATCH",
  headers: { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ content: "Asked for a case study in cold-chain logistics." }),
});
```

### Response `200`

The updated [note object](#the-note-object) in `data`.

### Errors

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No note with that ID in this workspace. |

---

## Delete a note

`DELETE /notes/{id}` · Scope: `notes:write`

Deletes the note permanently.

### Example

```bash
curl -X DELETE https://crm.empiraa.app/api/v1/notes/cm3ka2b7t0005ab7cx1y2z3w4 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```js
await fetch("https://crm.empiraa.app/api/v1/notes/cm3ka2b7t0005ab7cx1y2z3w4", {
  method: "DELETE",
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});
```

### Response `204`

No body.

### Errors

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No note with that ID in this workspace. |