# Notes

> The hiring team's notes on candidates. Part of the HireHappy API reference (https://hirehappy.io/docs/api).

Base URL: `https://api.hirehappy.io/v1`. Authenticate with `Authorization: Bearer <API key>`.

### List a candidate's notes

`GET https://api.hirehappy.io/v1/candidates/{candidate_id}/notes`

Scope: `candidates:read`

The hiring team's notes on the candidate, newest first.

**Path parameters**

| Name | Type | Description |
| --- | --- | --- |
| `candidate_id` | uuid | required |

**Example request**

```bash
curl "https://api.hirehappy.io/v1/candidates/c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f/notes" \
  -H "Authorization: Bearer $HIREHAPPY_API_KEY"
```

**Response** `200` (an array)

| Name | Type | Description |
| --- | --- | --- |
| `id` | uuid |  |
| `created_at` | datetime |  |
| `candidate_id` | uuid |  |
| `author_id` | uuid | The team member who wrote it; null for a note added through the API (api_key_id) or by someone who's since left. nullable |
| `api_key_id` | uuid | The API key it was added with; null once that key is revoked. nullable |
| `body` | string |  |

```json
[
  {
    "id": "f2a4c6e8-1b3d-4f5a-9c7e-0d2f4a6c8e1b",
    "created_at": "2026-10-26T09:30:00Z",
    "candidate_id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
    "author_id": null,
    "api_key_id": "5e1d9a47-2c3b-4f80-8d6e-7a9b0c1d2e3f",
    "body": "Strong system design answers. Worth a second interview."
  }
]
```

**Errors**: `401` the key is wrong, expired or revoked (api_key_required when missing); `403` the key isn't allowed candidates:read; `404` it isn't there, or belongs to another organization; `422` a parameter or field doesn't validate.

### Add a note

`POST https://api.hirehappy.io/v1/candidates/{candidate_id}/notes`

Scope: `candidates:write`

Add a note for the hiring team; the app shows it as added through the API.

**Path parameters**

| Name | Type | Description |
| --- | --- | --- |
| `candidate_id` | uuid | required |

**Request body** (application/json)

| Name | Type | Description |
| --- | --- | --- |
| `body` | string | required, min 1 chars, max 20,000 chars |

**Example request**

```bash
curl -X POST "https://api.hirehappy.io/v1/candidates/c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f/notes" \
  -H "Authorization: Bearer $HIREHAPPY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Referred by Sam on the platform team; they worked together at Bolt."
  }'
```

**Response** `201`

| Name | Type | Description |
| --- | --- | --- |
| `id` | uuid |  |
| `created_at` | datetime |  |
| `candidate_id` | uuid |  |
| `author_id` | uuid | The team member who wrote it; null for a note added through the API (api_key_id) or by someone who's since left. nullable |
| `api_key_id` | uuid | The API key it was added with; null once that key is revoked. nullable |
| `body` | string |  |

```json
{
  "id": "f2a4c6e8-1b3d-4f5a-9c7e-0d2f4a6c8e1b",
  "created_at": "2026-10-26T09:30:00Z",
  "candidate_id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
  "author_id": null,
  "api_key_id": "5e1d9a47-2c3b-4f80-8d6e-7a9b0c1d2e3f",
  "body": "Strong system design answers. Worth a second interview."
}
```

**Errors**: `400` a value is out of place; `401` the key is wrong, expired or revoked (api_key_required when missing); `403` the key isn't allowed candidates:write; `404` it isn't there, or belongs to another organization; `422` a parameter or field doesn't validate.
