---
title: "Create note"
method: POST
path: "/notes"
tags: ["Notes"]
---

# Create note

`POST /notes`

## Request

- Base URL: `https://api.100hires.com/v2`
- URL: `https://api.100hires.com/v2/notes`
- Auth: HTTP bearer

Creates a new discussion note for a candidate. Supports visibility control (all or private) and @mentions with email notifications.

## Query parameters

- `include` string

## Request body

- NoteCreateRequest
  - `candidate_id` string, required: Candidate ID (numeric) or alias
  - `body` string, required: Note content. Supports HTML.
  - `user_id` integer: Author user ID. If omitted, the authenticated user is used
  - `visibility` string: Visibility: 'all' (default) or 'private'
  - `mention_user_ids` integer[]: Array of user IDs to mention. Mentioned users receive email notifications and their `@name` or `@login` references in the body are replaced with HTML mention markup.

## Response `200`

Created note

- Note
  - `id` integer, required: Unique identifier
  - `candidate_id` integer, required: ID of the candidate this note belongs to
  - `user_id` integer, required: Author user ID (always present)
  - `url_backoffice` string, uri: Absolute backoffice URL to the candidate's discussion tab where this note appears in the 100Hires recruiter app. Use to render deep-links in agent UIs.
  - `body` string: Note content (may contain HTML). Mentioned users are wrapped in `<span class="mention-area">` markup. Present only when `view=full` (default); replaced with `body_preview` when `view=summary`.
  - `body_preview` string: First 200 UTF-8 characters of the note content with a `...` suffix when truncated. Present only when `view=summary`; replaces `body` to keep list responses inside the agent context budget.
  - `visibility` string, required: Visibility: 'all' (visible to team) or 'private' (author only)
  - `created_at` integer, required: Unix timestamp (seconds)
  - `updated_at` integer, required: Unix timestamp (seconds)
  - `user` NoteUser
    - `id` integer, required: User ID.
    - `full_name` string, required: User full name.
    - `photo` string, nullable: Profile photo URL.
  - `candidate` Candidate
    - `id` integer, required: Unique identifier
    - `alias` string, nullable: Short alphanumeric alias used in profile URLs. Use this to build candidate profile links — `https://app.100hires.com/candidate/{alias}`. Also accepted as `{id}` in API requests.
    - `url_backoffice` string, uri: Absolute backoffice URL of the candidate in the 100Hires recruiter app. Use to render deep-links in agent UIs.
    - `company_id` integer, required: ID of the company this candidate belongs to
    - `first_name` string, nullable: Candidate's first name
    - `last_name` string, nullable: Candidate's last name
    - `emails` string[], nullable: List of candidate email addresses
    - `phones` string[], nullable: List of candidate phone numbers
    - `source` IdName
      - `id` integer, required: Unique identifier.
      - `name` string, required: Display name.
    - `origin` IdName
      - `id` integer, required: Unique identifier.
      - `name` string, required: Display name.
    - `profile` ProfileAnswer[]: Candidate profile field answers (application form responses). Present only when `view=full` (default); omitted entirely when `view=summary` to keep list responses inside the agent context budget — a single candidate can carry dozens of free-form answers.
      - `question_id` integer, required: Question ID.
      - `question_text` string, required: Question label.
      - `value` unknown, required
    - `ip` string, nullable: IP address from which the candidate applied
    - `applications` CandidateApplicationSummary[]: Summary of all applications this candidate has across jobs
      - `id` integer, required: Application ID.
      - `job` object, required: Job summary (id, title, status).
        - `id` integer, required
        - `title` string, required
      - `stage` IdName
        - `id` integer, required: Unique identifier.
        - `name` string, required: Display name.
    - `created_at` integer, required: Unix timestamp (seconds)
    - `updated_at` integer, required: Unix timestamp (seconds)
    - `last_message_at` integer, nullable: Unix timestamp (seconds) of the most recent message (email or SMS) sent to or received from this candidate. Null if no messages exist.
    - `days_since_last_message` integer, nullable: Number of whole days since the last message. Computed at request time. Null if no messages exist.

## Other responses

- `400`: Validation error
- `401`: Unauthorized
- `403`: Forbidden
- `415`: Content-Type must be application/json
- `429`: Too many requests

---

[API](https://skmtc.dev/100hires/apis/100hires-api.md) · [All operations](https://skmtc.dev/100hires/apis/100hires-api/llms.txt) · [OpenAPI document](https://skmtc.dev/100hires/apis/100hires-api/revisions/e63e2d3115f7?raw)