Docs

Search the docs

Guides, sections and API endpoints

API reference

Notes

The hiring team's notes on candidates.

List a candidate's notes

get/candidates/{candidate_id}/notes

Needs 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.

  • iduuid
  • created_atdatetime
  • candidate_iduuid
  • author_iduuidnullable
    The team member who wrote it; null for a note added through the API (api_key_id) or by someone who's since left.
  • api_key_iduuidnullable
    The API key it was added with; null once that key is revoked.
  • 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"
Response 200
[
  {
    "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}/notes

Needs 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

  • bodystringRequired
    min 1 charsmax 20,000 chars

Returns 201

  • iduuid
  • created_atdatetime
  • candidate_iduuid
  • author_iduuidnullable
    The team member who wrote it; null for a note added through the API (api_key_id) or by someone who's since left.
  • api_key_iduuidnullable
    The API key it was added with; null once that key is revoked.
  • 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."
  }'
Response 201
{
  "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."
}