Move candidate to a stage
Move a candidate to another stage of a job.
POST https://cotlet.dev/api/v1/recruiterflow/jobs/{job_id}/candidates/{candidate_id}/stage/move
write Confirm
Moves one candidate to the stage you name, as the stage name on the job card does. The move shows in the Activity Log with your user and the time. A stage with mandatory fields needs them in fields; without them the call returns the missing fields and moves nothing. A stage that asks for placement details (Hired) or a disqualification reason (Rejected) also returns its questions instead of moving. Stage changes can start automations and sequences your admins set up, which can email the candidate. By default you confirm each call; you can switch that off for this tool.
Parameters
| Name | Type | Description |
|---|---|---|
| job_id string required | string | Job id from list_jobs. |
| candidate_id string required | string | Candidate id from list_job_candidates. |
| stage string required | string | Stage name as get_job shows it. |
| fields object | object | Values for the fields the stage makes mandatory. |
Request
curl -X POST https://cotlet.dev/api/v1/recruiterflow/jobs/48213/candidates/771204/stage/move \
-H "Authorization: Bearer $COTLET_API_KEY" \
-H "Content-Type: application/json" \
-d '{"stage":"Phone Screen"}'result = client.call("recruiterflow", "move_candidate_stage", {"job_id":"48213","candidate_id":"771204","stage":"Phone Screen"})const result = await cotlet.call('recruiterflow', 'move_candidate_stage', {"job_id":"48213","candidate_id":"771204","stage":"Phone Screen"});cotlet call recruiterflow move_candidate_stage --data '{"job_id":"48213","candidate_id":"771204","stage":"Phone Screen"}'Example response
{
"candidate_id": "771204",
"job_id": "48213",
"from": "Sourced",
"to": "Phone Screen",
"moved_at": "2026-10-23T09:00:00Z",
"moved_by": "Dana Reyes"
}