---
title: "List candidates"
method: GET
path: "/candidates"
tags: ["Candidates"]
---

# List candidates

`GET /candidates`

## Request

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

Returns a paginated candidate list for one company or all companies accessible by the API key. Use filters for deduplication, exports, and incremental synchronization jobs.

## Query parameters

- `company_id` integer
- `job_id` integer
- `stage_id` integer
- `email` string
- `q` string
- `full_name` string
- `linkedin` string
- `created_after` union
  - integer
  - string
- `updated_after` union
  - integer
  - string
- `include` 'applications'
- `page` integer
- `size` integer
- `view` 'full' | 'summary'

## Response `200`

Candidate list

- CandidateListResponse
  - `candidates` Candidate[], required: Array of candidates.
    - `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.
  - `pagination` Pagination, required
    - `page_size` integer, required: Items per page.
    - `page_count` integer, required: Total number of pages.
    - `page` integer, required: Current page number.
    - `total_count` integer, required: Total number of items.

## 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)