---
title: "Patch Candidate Status"
method: PATCH
path: "/gtm-internal/candidate-status/{candidate_id}"
tags: ["gtm-internal"]
---

# Patch Candidate Status

`PATCH /gtm-internal/candidate-status/{candidate_id}`

## 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/{candidate_id}`
- Auth: OAuth 2
  - Password
  - Token URL: `/auth/login`

Edit the editable board fields on one candidate row. Same validation
semantics as the MCP ``upsert_candidate`` (stage against the shared
CANDIDATE_STAGES vocabulary; blank strings clear), and the same audit
contract — every write lands a ``candidate.update`` row with before/after
snapshots, the change trail that stands in for ATS-style stage history.
Returns the refreshed row so the FE swaps it in place.

## Path parameters

- `candidate_id` string, required

## Request body

- CandidateStatusPatchRequest: Board-row editor — the candidate columns the pipeline board edits in place. Only fields present in the body are applied; an explicit null (or blank string) CLEARS the value. Identity (full_name/slug) and the research anchors (investigation / work-sample domain) are deliberately read-only here — they belong to the recruiting routines' write door (``upsert_candidate``), not inline table edits.
  - `role` string, nullable
  - `stage` string, nullable
  - `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, date, nullable
  - `last_touch` string, date, nullable

## Response `200`

Successful Response

- CandidateStatusRow
  - `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

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