100Hires Notes API

openapi: 3.2.0
info:
  title: 100Hires Notes API
  version: 2.0.0
  description: '## Introduction to the 100Hires ATS API

    The 100Hires ATS API (v2) helps you automate recruiting workflows end-to-end: candidates, applications, jobs, forms, notes, and partner-company operations. All endpoints return JSON and use bearer authentication. ## OpenAPI Spec

    The 100Hires ATS API follows the OpenAPI 3.x specification. Download the machine-readable spec for use in MCP servers, Cursor, Claude Code, or any OpenAPI tooling:


    `GET https://api.100hires.com/v2/openapi.json`


    ## Authentication

    Send API token in the `Authorization` header for every request:


    `Authorization: Bearer `


    Each API key is tied to a specific **user + company** pair. If the same user belongs to multiple companies, they need a separate key for each company. All actions performed through the API are attributed to the key owner. You can generate or view your API key at https://app.100hires.com/settings/integrations


    ### API Key Verification

    API keys for **unverified companies** are created in a disabled state and will return `401 Unauthorized` until the company passes verification. Once your company is verified, API keys start working automatically — no action required. If your key returns `401` and you believe your company should be verified, contact **support@100hires.com**. ## Rate Limits

    API keys that are not yet approved, such as keys created during the free trial, are subject to a hard rate limit of **1,000 requests per 10 minutes** per company. All API keys and MCP connections of a company share this limit. If your company is managed by a partner, it shares the partner''s limit. Personal API keys are approved automatically when the company starts a paid subscription. Requests over the limit receive a `429 Too Many Requests` response. ### Rate limit headers

    Unapproved keys include these headers on every response:


    | Header | Description |

    |--------|-------------|

    | `X-RateLimit-Limit` | Maximum requests allowed in the current window |

    | `X-RateLimit-Remaining` | Requests remaining in the current window |

    | `X-RateLimit-Reset` | Unix timestamp (seconds) when the window resets |


    ### Handling 429 responses

    When you receive a `429` response, wait until `X-RateLimit-Reset` before retrying. Do not retry immediately — repeated 429s may extend the cooldown. To remove rate limits for your integration, contact **support@100hires.com** with your use case. ## Content-Type

    All request bodies **must** use `Content-Type: application/json`. Sending `application/x-www-form-urlencoded`, `multipart/form-data`, or any other content type

    will result in a `415 Unsupported Media Type` error. ## Responses and Errors

    Standard HTTP status codes are used (`2xx`, `4xx`, `5xx`). All error responses are wrapped in an `error` object containing `name`, `message`, `code`, and `status`. Validation errors additionally include field-level details in `error.validation_errors`. See the Error handling section below for the full format and status table. ## Pagination

    List endpoints use `page` (1-based) and `size` (1-100, default 20). Paginated responses follow:

    `{ "": [...], "pagination": { "page_size", "page_count", "page", "total_count" } }`. ## Lists

    List routes are optimized for synchronization and operational dashboards. Most list endpoints support tenant scoping through optional `company_id` (when allowed by API key context). ## Confidential Data

    Some candidate profile values can be masked by account-level pricing/access rules. Integrations should not assume all profile fields are always fully visible. ## Customizing the Response

    Use endpoint filters (`status`, `job_id`, timestamps, taxonomy IDs, etc.) to minimize payload size and improve sync efficiency. Build incremental sync flows around timestamp filters where available. ## Supported File Formats

    File uploads use base64 payloads with metadata:

    `data`, `file_name`, `mime_type` (and optionally `size`). This format is used for candidate files, resumes, attachments, and logos.'
servers:
- url: https://api.100hires.com/v2
  description: Production API endpoint
security:
- BearerAuth: []
tags:
- name: Notes
  description: Discussion notes linked to candidates for recruiter collaboration and context sharing.
paths:
  /notes:
    get:
      tags:
      - Notes
      summary: List notes by candidate
      operationId: listNotes
      parameters:
      - name: candidate_id
        in: query
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9_-]+$
        description: Candidate ID (numeric) or alias
      - $ref: '#/components/parameters/NoteIncludeQuery'
      - $ref: '#/components/parameters/PageQuery'
      - $ref: '#/components/parameters/SizeQuery'
      - $ref: '#/components/parameters/ViewQuery'
      responses:
        '200':
          description: Note list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoteListResponse'
              example:
                notes:
                - id: 67890
                  candidate_id: 12345
                  user_id: 1
                  body: Strong technical background, moving to next round.
                  visibility: all
                  created_at: 1711036800
                  updated_at: 1711036800
                pagination:
                  page_size: 25
                  page_count: 1
                  page: 1
                  total_count: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      description: Returns paginated discussion notes for a candidate. Use for shared recruiter context and timeline synchronization.
    post:
      tags:
      - Notes
      summary: Create note
      operationId: createNote
      parameters:
      - $ref: '#/components/parameters/NoteIncludeQuery'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NoteCreateRequest'
            example:
              candidate_id: 12345
              body: Hey @Alice Smith, please review this candidate.
              visibility: all
              mention_user_ids:
              - 42
      responses:
        '200':
          description: Created note
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Note'
              example:
                id: 67890
                candidate_id: 12345
                user_id: 1
                body: Hey <span class="mention-area" contenteditable="false"><span class="highlight"><span class="mentiony-link">Alice Smith</span></span></span>, please review this candidate.
                visibility: all
                created_at: 1711036800
                updated_at: 1711036800
        '400':
          $ref: '#/components/responses/ValidationError'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      description: Creates a new discussion note for a candidate. Supports visibility control (all or private) and @mentions with email notifications.
  /notes/{id}:
    get:
      tags:
      - Notes
      summary: Get note
      operationId: getNote
      parameters:
      - $ref: '#/components/parameters/IdPath'
      - $ref: '#/components/parameters/NoteIncludeQuery'
      responses:
        '200':
          description: Note
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Note'
              example:
                id: 67890
                candidate_id: 12345
                user_id: 1
                body: Strong technical background, moving to next round.
                visibility: all
                created_at: 1711036800
                updated_at: 1711036800
                user:
                  id: 1
                  full_name: Alice Smith
                  photo: https://cdn.100hires.com/photos/alice.jpg
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '404':
          $ref: '#/components/responses/NotFound'
      description: Returns a single note with author and visibility metadata. Use `include=user` to load author details, `include=candidate` to embed the full candidate payload (with `url_backoffice`).
    put:
      tags:
      - Notes
      summary: Update note
      operationId: updateNote
      parameters:
      - $ref: '#/components/parameters/IdPath'
      - $ref: '#/components/parameters/NoteIncludeQuery'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NoteUpdateRequest'
      responses:
        '200':
          description: Updated note
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Note'
              example:
                id: 67890
                candidate_id: 12345
                user_id: 1
                body: 'Updated: Strong technical background, scheduled final interview.'
                visibility: all
                created_at: 1711036800
                updated_at: 1711123200
        '400':
          $ref: '#/components/responses/ValidationError'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '404':
          $ref: '#/components/responses/NotFound'
      description: Updates note body and/or visibility without creating a new timeline item. Use for corrections and moderation workflows.
    delete:
      tags:
      - Notes
      summary: Delete note
      operationId: deleteNote
      parameters:
      - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              example:
                success: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '404':
          $ref: '#/components/responses/NotFound'
      description: Deletes a note from active collaboration views. Use for moderation policies and data cleanup operations.
components:
  schemas:
    IdName:
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: integer
          description: Unique identifier.
        name:
          type: string
          description: Display name.
    NoteUser:
      type: object
      required:
      - id
      - full_name
      properties:
        id:
          type: integer
          description: User ID.
        full_name:
          type: string
          description: User full name.
        photo:
          type:
          - string
          - 'null'
          description: Profile photo URL.
    NoteCreateRequest:
      type: object
      required:
      - candidate_id
      - body
      properties:
        candidate_id:
          type: string
          pattern: ^[A-Za-z0-9_-]+$
          description: Candidate ID (numeric) or alias
        body:
          type: string
          description: Note content. Supports HTML.
        user_id:
          type: integer
          description: Author user ID. If omitted, the authenticated user is used
        visibility:
          type: string
          description: 'Visibility: ''all'' (default) or ''private'''
        mention_user_ids:
          type: array
          items:
            type: integer
          description: 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.
      additionalProperties: false
    CandidateApplicationSummary:
      type: object
      required:
      - id
      - job
      properties:
        id:
          type: integer
          description: Application ID.
        job:
          type: object
          description: Job summary (id, title, status).
          required:
          - id
          - title
          properties:
            id:
              type: integer
            title:
              type: string
        stage:
          oneOf:
          - $ref: '#/components/schemas/IdName'
          - type: 'null'
    NoteUpdateRequest:
      type: object
      properties:
        body:
          type: string
          description: Note content. Supports HTML.
        visibility:
          type: string
          description: 'Visibility: ''all'' (default) or ''private''.'
      additionalProperties: false
    ProfileAnswer:
      type: object
      required:
      - question_id
      - question_text
      - value
      properties:
        question_id:
          type: integer
          description: Question ID.
        question_text:
          type: string
          description: Question label.
        value:
          description: Answer value (string, array, or null).
    NoteListResponse:
      type: object
      required:
      - notes
      - pagination
      properties:
        notes:
          type: array
          description: Array of notes.
          items:
            $ref: '#/components/schemas/Note'
        pagination:
          $ref: '#/components/schemas/Pagination'
    Pagination:
      type: object
      required:
      - page_size
      - page_count
      - page
      - total_count
      properties:
        page_size:
          type: integer
          description: Items per page.
        page_count:
          type: integer
          description: Total number of pages.
        page:
          type: integer
          description: Current page number.
        total_count:
          type: integer
          description: Total number of items.
    ValidationError:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          description: Validation error details object.
          required:
          - name
          - validation_errors
          properties:
            name:
              type: string
              description: Always "Validation Error" for validation failures
              example: Validation Error
            message:
              type: string
            code:
              type: integer
              example: 0
            status:
              type: integer
              example: 400
            validation_errors:
              type: object
              description: Field-level validation errors (field name to error message)
              additionalProperties:
                type: string
              example:
                email: Email cannot be blank.
                first_name: First Name cannot be blank.
      example:
        error:
          name: Validation Error
          message: ''
          code: 0
          status: 400
          validation_errors:
            email: Email cannot be blank.
            first_name: First Name cannot be blank.
    Note:
      type: object
      required:
      - id
      - candidate_id
      - user_id
      - visibility
      - created_at
      - updated_at
      properties:
        id:
          type: integer
          description: Unique identifier
        candidate_id:
          type: integer
          description: ID of the candidate this note belongs to
        user_id:
          type: integer
          description: Author user ID (always present)
        url_backoffice:
          type: string
          format: uri
          description: 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.
          example: https://app.100hires.com/candidate/dtGeby2#/profile/discussion
        body:
          type: string
          description: 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:
          type: string
          description: 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:
          type: string
          description: 'Visibility: ''all'' (visible to team) or ''private'' (author only)'
        created_at:
          type: integer
          format: int64
          description: Unix timestamp (seconds)
        updated_at:
          type: integer
          format: int64
          description: Unix timestamp (seconds)
        user:
          description: Author details (only with include=user)
          allOf:
          - $ref: '#/components/schemas/NoteUser'
        candidate:
          oneOf:
          - $ref: '#/components/schemas/Candidate'
          - type: 'null'
          description: Embedded candidate payload (included when requested via `include=candidate`). Use `candidate.url_backoffice` to deep-link UI widgets to the candidate profile in the recruiter app.
    Candidate:
      type: object
      required:
      - id
      - company_id
      - created_at
      - updated_at
      properties:
        id:
          type: integer
          description: Unique identifier
        alias:
          type:
          - string
          - 'null'
          description: 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.
          example: dtGeby2
        url_backoffice:
          type: string
          format: uri
          description: Absolute backoffice URL of the candidate in the 100Hires recruiter app. Use to render deep-links in agent UIs.
          example: https://app.100hires.com/candidate/dtGeby2
        company_id:
          type: integer
          description: ID of the company this candidate belongs to
        first_name:
          type:
          - string
          - 'null'
          description: Candidate's first name
        last_name:
          type:
          - string
          - 'null'
          description: Candidate's last name
        emails:
          oneOf:
          - type: array
            items:
              type: string
              format: email
          - type: 'null'
          description: List of candidate email addresses
        phones:
          oneOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: List of candidate phone numbers
        source:
          oneOf:
          - $ref: '#/components/schemas/IdName'
          - type: 'null'
          description: How the candidate was sourced (e.g. LinkedIn, Referral)
        origin:
          oneOf:
          - $ref: '#/components/schemas/IdName'
          - type: 'null'
          description: Where the candidate originally came from (e.g. job board name)
        profile:
          type: array
          items:
            $ref: '#/components/schemas/ProfileAnswer'
          description: 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.
        ip:
          type:
          - string
          - 'null'
          description: IP address from which the candidate applied
        applications:
          type: array
          items:
            $ref: '#/components/schemas/CandidateApplicationSummary'
          description: Summary of all applications this candidate has across jobs
        created_at:
          type: integer
          format: int64
          description: Unix timestamp (seconds)
        updated_at:
          type: integer
          format: int64
          description: Unix timestamp (seconds)
        last_message_at:
          type:
          - integer
          - 'null'
          format: int64
          description: 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:
          type:
          - integer
          - 'null'
          description: Number of whole days since the last message. Computed at request time. Null if no messages exist.
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          description: Error details object.
          required:
          - name
          - message
          - code
          - status
          properties:
            name:
              type: string
              description: Human-readable error type (e.g. "Not Found", "Bad Request", "Forbidden")
              example: Not Found
            message:
              type: string
              description: Detailed error message
              example: Candidate not found
            code:
              type: integer
              description: Application error code (0 for generic errors)
              example: 0
            status:
              type: integer
              description: HTTP status code
              example: 404
      example:
        error:
          name: Not Found
          message: Candidate not found
          code: 0
          status: 404
    SuccessResponse:
      type: object
      required:
      - success
      properties:
        success:
          type: boolean
          description: Always true on success.
  responses:
    NotFound:
      description: Not found
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              name: Not Found
              message: Candidate not found
              code: 0
              status: 404
    Unauthorized:
      description: Unauthorized
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              name: Unauthorized
              message: Your request was made with invalid credentials.
              code: 0
              status: 401
    TooManyRequests:
      description: Too many requests
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              name: Too Many Requests
              message: Rate limit exceeded
              code: 0
              status: 429
    BadRequest:
      description: Bad request
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              name: Bad Request
              message: Invalid request parameters
              code: 0
              status: 400
    Forbidden:
      description: Forbidden
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              name: Forbidden
              message: You are not allowed to perform this action.
              code: 0
              status: 403
    UnsupportedMediaType:
      description: Content-Type must be application/json
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              name: Unsupported Media Type
              message: Content-Type must be application/json
              code: 0
              status: 415
    ValidationError:
      description: Validation error
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'
  headers:
    RateLimitRemaining:
      description: Remaining requests in the current rate-limit window. Returned for unapproved API keys.
      schema:
        type: integer
    RateLimitReset:
      description: Unix timestamp when the current rate-limit window resets. Returned for unapproved API keys.
      schema:
        type: integer
        format: int64
    RateLimitLimit:
      description: Request limit for the current rate-limit window. Returned for unapproved API keys.
      schema:
        type: integer
  parameters:
    SizeQuery:
      name: size
      in: query
      required: false
      description: Number of items per page (1–100). Defaults to 20.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    IdPath:
      name: id
      in: path
      required: true
      description: Resource ID (numeric).
      schema:
        type: integer
    ViewQuery:
      name: view
      in: query
      required: false
      description: 'Response shape selector for list endpoints. `full` (default) returns every field

        — backward-compatible with pre-existing clients. `summary` returns a thinned

        payload designed for agent-friendly list browsing: heavy fields (description

        HTML, embedded profile answers, full message bodies, embedded relations, etc.)

        are omitted or replaced with `*_preview` truncations. Use `summary` when paging

        through large result sets and fetch a single record with the corresponding

        `GET /{resource}/{id}` endpoint when full data is needed.

        '
      schema:
        type: string
        enum:
        - full
        - summary
        default: full
    NoteIncludeQuery:
      name: include
      in: query
      required: false
      schema:
        type: string
      description: 'Comma-separated list of related resources to include. Supported: `user` — author details, `candidate` — full candidate payload with `url_backoffice` for UI deep-linking.'
      style: form
      explode: false
    PageQuery:
      name: page
      in: query
      required: false
      description: Page number (1-based). Defaults to 1.
      schema:
        type: integer
        minimum: 1
        default: 1
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: APIKey
      description: 'Provide API token in header: `Authorization: Bearer <token>`. Each key is scoped to a specific user + company pair.'
    CompanySlugAuth:
      type: apiKey
      in: header
      name: X-Company-Slug
      description: 'Company slug for career site public endpoints. Alternative: pass as query param `company_slug`.'
x-tagGroups:
- name: Recruiting Operations
  tags:
  - Candidates
  - Applications
  - Interviews
  - Jobs
  - Evaluations
  - Notes
  - Messages
  - Notification Messages
  - Forms
  - Questions
  - Email Templates
  - Nurture Campaigns
  - Template Placeholders
  - Users
  - Attachments
- name: Organization and Settings
  tags:
  - Companies
  - Taxonomy
  - Billing
  - Feedback
- name: Career Site (Public)
  tags:
  - Career Site