API reference
Notes
The hiring team's notes on candidates.
List a candidate's notes
get
/candidates/{candidate_id}/notesNeeds the candidates:read scope
The hiring team's notes on the candidate, newest first.
Path parameters
candidate_iduuidRequired
Returns 200
An array of objects like this one, all of them.
iduuidcreated_atdatetimecandidate_iduuid- The team member who wrote it; null for a note added through the API (api_key_id) or by someone who's since left.
author_iduuidnullable - The API key it was added with; null once that key is revoked.
api_key_iduuidnullable bodystring
Errors
- 401The key is wrong, expired or revoked (api_key_required when missing)
invalid_api_key - 403The key isn't allowed candidates:read
insufficient_scope - 404It isn't there, or belongs to another organization
resource_not_found - 422A parameter or field doesn't validate
missing, uuid_parsing, …
curl "https://api.hirehappy.io/v1/candidates/c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f/notes" \
-H "Authorization: Bearer $HIREHAPPY_API_KEY"[
{
"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."
}
]Add a note
post
/candidates/{candidate_id}/notesNeeds the candidates:write scope
Add a note for the hiring team; the app shows it as added through the API.
Path parameters
candidate_iduuidRequired
Bodyapplication/json
bodystringRequiredmin 1 charsmax 20,000 chars
Returns 201
iduuidcreated_atdatetimecandidate_iduuid- The team member who wrote it; null for a note added through the API (api_key_id) or by someone who's since left.
author_iduuidnullable - The API key it was added with; null once that key is revoked.
api_key_iduuidnullable bodystring
Errors
- 400A value is out of place
validation_error - 401The key is wrong, expired or revoked (api_key_required when missing)
invalid_api_key - 403The key isn't allowed candidates:write
insufficient_scope - 404It isn't there, or belongs to another organization
resource_not_found - 422A parameter or field doesn't validate
missing, uuid_parsing, …
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."
}'{
"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."
}