Advance a candidate

Move a candidate to the next pipeline step. Scope: pipeline:write.

POST/api/v1/candidate-steps/{id}/advance 🔒 API key

Force-advances a candidate from the given step to the next step in their pipeline. Scope: pipeline:write. The {id} is a CandidateRoleStep id (a candidate’s progress row for one step — see candidate steps). Requires authority to manage the candidate’s steps (HR rep, moderator, owner, or admin).

No email; side-effects still run

A v1 transition sends no email (neither the candidate “step approved” nor the HR “next step ready” notifications). Non-email side-effects still run — contract auto-generation and activity logging.

Path parameters

Parameter	Type	Description
`id`	string	The CandidateRoleStep id.

Request body (optional)

Field	Type	Description
`notes`	string	Validation note recorded on the step.

Example request

curl -X POST https://app.talent-ray.com/api/v1/candidate-steps/crs_1/advance \
  -H "Authorization: Bearer tr_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "notes": "Strong interview; advancing." }'

Response

200 OK

{
  "success": true,
  "step": { "id": "crs_1", "roleId": "role_eng_be", "roleStepId": "step_cv", "name": "CV Screening", "order": 1, "stepType": "cv_screening", "status": "validated", "validatedAt": "2026-06-05T12:00:00Z", "validationScore": 78 }
}

Status codes

Status	Meaning
`200`	Advanced; `step` is the now-validated step.
`401`	No valid API key.
`403`	`insufficient_scope` (missing `pipeline:write`) or `forbidden` (cannot manage this candidate’s steps).
`404`	Step not found, or not visible to the key.
`409`	`conflict` — the step is already completed or rejected.
`429`	Rate limit exceeded.