---
title: "Update a candidate"
method: PATCH
path: "/v1/candidates/{candidateId}"
tags: ["Candidate"]
---

# Update a candidate

`PATCH /v1/candidates/{candidateId}`

Updates the supplied hiring-team assignments and candidate profile fields. Omitted fields are preserved; nullable team IDs clear their assignment, clear_preferred_email clears only when true, and an empty conflict list removes all listed conflicts. Some writable fields are intentionally write-only because the candidate summary RPC does not return them.

## Path parameters

- `candidateId` string, required — a candidate ID. Accepts the canonical prefixed compact UUID, a prefixed dashed UUID, a bare dashed UUID, or a bare compact UUID; input is case-insensitive.

## Request body

- CandidatePatch
  - `recruiter_id` string, nullable — an employee ID. Accepts the canonical prefixed compact UUID, a prefixed dashed UUID, a bare dashed UUID, or a bare compact UUID; input is case-insensitive.
  - `coordinator_id` string, nullable — an employee ID. Accepts the canonical prefixed compact UUID, a prefixed dashed UUID, a bare dashed UUID, or a bare compact UUID; input is case-insensitive.
  - `sourcer_id` string, nullable — an employee ID. Accepts the canonical prefixed compact UUID, a prefixed dashed UUID, a bare dashed UUID, or a bare compact UUID; input is case-insensitive.
  - `clear_preferred_email` boolean — True clears the preferred email; omit or false preserves it.
  - `timezone` string — Replaces the timezone; omit to preserve.
  - `preferred_phone_number` string — Replaces the preferred phone number; omit to preserve. Write-only.
  - `locale` string — Replaces the locale; omit to preserve. Write-only.
  - `conflict_of_interest_employee_ids` string[] — Replaces the full conflict-of-interest list; an empty array clears it and omission preserves it. Write-only.

## Response `200`

Success

- Candidate
  - `id` string, required — Canonical candidate ID (can_ followed by 32 lowercase hexadecimal UUID characters).
  - `name` object, required
    - `full` string, required
    - `given` string, nullable, required
    - `family` string, nullable, required
  - `primary_email` string, email, nullable, required
  - `additional_emails` string[], nullable, required — Additional candidate email addresses. Null means PII was redacted because the candidate is anonymized; an empty array means no additional email addresses.
  - `phone_numbers` string[], nullable, required — Candidate phone numbers. Null means PII was redacted because the candidate is anonymized; an empty array means no phone numbers.
  - `timezone` string, nullable, required
  - `linkedin_url` string, uri, nullable, required
  - `preferred_name` string, nullable, required
  - `recruiter` object, nullable, required
    - `id` string, required — Canonical employee ID (emp_ followed by 32 lowercase hexadecimal UUID characters).
    - `name` string, required
  - `coordinator` object, nullable, required
    - `id` string, required — Canonical employee ID (emp_ followed by 32 lowercase hexadecimal UUID characters).
    - `name` string, required
  - `ats` object, nullable, required
    - `type` 'GREENHOUSE' | 'ASHBY' | 'LEVER' | 'WORKDAY' | 'SMARTRECRUITERS' | 'GEM' | 'KOMBO', required
    - `id` string, required
  - `anonymized` boolean, required
  - `created_at` string, date-time, required — ISO 8601 timestamp.
  - `updated_at` string, date-time, required — ISO 8601 timestamp.
  - `app_url` string, uri, required

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not found
- `409` — Conflict
- `410` — Gone
- `500` — Internal error

---

[API](https://skmtc.dev/modernloop/apis/modernloop-platform-api.md) · [All operations](https://skmtc.dev/modernloop/apis/modernloop-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/modernloop/modernloop-platform-api/revisions/33a0f9f44e4c/schema)