---
title: "List Candidate Status"
method: GET
path: "/gtm-internal/candidate-status"
tags: ["gtm-internal"]
---

# List Candidate Status

`GET /gtm-internal/candidate-status`

## Request

- Base URL: `https://api-v1.unusual.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api-v1.unusual.ai/gtm-internal/candidate-status`
- Auth: OAuth 2
  - Password
  - Token URL: `/auth/login`

Candidate Status board — one row per recruiting candidate under a
pipeline lens (default "active": open stages + not-yet-triaged). Optional
exact ``stage`` filter (validated against CANDIDATE_STAGES — a typo'd
filter errors, never silently narrows the board) and ``q`` substring match
over name/company/role/email (the MCP list_candidates' search fields).
Rows are built then sorted/paged in memory under the same cap discipline
as the account board — the tier is tens of rows today.

## Query parameters

- `lens` string
- `stage` string, nullable
- `q` string, nullable
- `sort_by` string
- `sort_dir` string
- `page` integer
- `page_size` integer

## Response `200`

Successful Response

- CandidateStatusListResponse
  - `rows` CandidateStatusRow[], required
    - `candidate_id` string, required
    - `full_name` string, required
    - `slug` string, nullable
    - `role` string, nullable
    - `stage` string, nullable
    - `active` boolean
    - `source` string, nullable
    - `referrer` string, nullable
    - `email` string, nullable
    - `linkedin` string, nullable
    - `location` string, nullable
    - `current_company` string, nullable
    - `current_role` string, nullable
    - `next_step` string, nullable
    - `next_step_date` string, nullable
    - `last_touch` string, nullable
    - `investigation_id` string, nullable
    - `work_sample_domain_id` string, nullable
    - `work_sample_host` string, nullable
    - `report_count` integer
  - `total` integer, required
  - `lens` string, required
  - `page` integer
  - `page_size` integer
  - `truncated` boolean

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/unusual/apis/dashboard-server.md) - [All operations](https://skmtc.dev/unusual/apis/dashboard-server/llms.txt) - [OpenAPI document](https://skmtc.dev/unusual/apis/dashboard-server/revisions/89f716930ead?raw)