Update a candidate

Updates a curated subset of a candidate’s fields. Scope: candidates:write. Requires employer-write authority in one of the candidate’s organizations (admins bypass; hiring managers are read-only). Send only the fields you want to change — unknown fields are ignored, wrong-typed fields return 400.

Path parameters

Parameter	Type	Description
id	string	The candidate id.

Request body

Field	Type	Description
fullName	string	Candidate’s full name.
status	string	Candidate status.
email	string | null	Email (validated).
phone	string | null	Phone (validated).
summary	string | null	Free-text summary.

Example request

curl -X PATCH https://app.talent-ray.com/api/v1/candidates/cand_1 \
  -H "Authorization: Bearer tr_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "Active", "phone": "+905551112233" }'

Response

200 OK — the updated candidate (same shape as Get a candidate).

Status codes

Status	Meaning
200	Updated.
400	bad_request — invalid or empty body.
401	No valid API key.
403	insufficient_scope (missing candidates:write) or forbidden (no write authority in the candidate’s org).
404	Not found, or not visible to the key.
429	Rate limit exceeded.