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

# List Candidates

`GET /api/candidates/list`

## Request

- Base URL: `https://api.thebetterhire.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.thebetterhire.ai/api/candidates/list`
- Auth: HTTP bearer

List all candidates for the organization

Args:
    status_filter: Filter by status ('active', 'hired', 'rejected')
    search: Search by name or email
    hiring_company: Filter to candidates with ≥1 interview against a
        role whose hiring_company_display matches (trim + case-
        insensitive). Drives the agency-mode "show me Tesco
        candidates" view. Single value for v1 — multi-select is a
        Phase 2 question if a customer asks.
    limit: Maximum results per page
    offset: Pagination offset

Returns:
    Paginated list of candidates with interview counts

## Query parameters

- `status_filter` string, nullable
- `search` string, nullable
- `hiring_company` string, nullable
- `mine` boolean
- `limit` integer
- `offset` integer

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/thebetterhire/apis/interanalysis-b2b-api.md) · [All operations](https://skmtc.dev/thebetterhire/apis/interanalysis-b2b-api/llms.txt) · [OpenAPI document](https://skmtc.dev/thebetterhire/apis/interanalysis-b2b-api/revisions/c8ad03e900ea?raw)