Reject a candidate

Reject a candidate at the given step. Scope: pipeline:write.

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

Rejects the candidate at the given step, setting the candidate role to Not Selected. Scope: pipeline:write. The {id} is a CandidateRoleStep id. Requires authority to manage the candidate’s steps (HR rep, moderator, owner, or admin).

No email

A v1 reject sends no email. Activity is logged and the organization status cache is synced.

Path parameters

Parameter	Type	Description
`id`	string	The CandidateRoleStep id.

Request body (optional)

Field	Type	Description
`outcomeNotes`	string	Recorded as the rejection reason.
`outcomeType`	string	Structured outcome classification.
`outcomeReason`	string	Structured outcome reason.

Example request

curl -X POST https://app.talent-ray.com/api/v1/candidate-steps/crs_3/reject \
  -H "Authorization: Bearer tr_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "outcomeReason": "skills_mismatch", "outcomeNotes": "Below the bar on system design." }'

Response

200 OK

{
  "success": true,
  "step": { "id": "crs_3", "roleId": "role_eng_be", "roleStepId": "step_interview", "name": "Technical Interview", "order": 3, "stepType": "interview", "status": "rejected", "rejectedAt": "2026-06-05T12:00:00Z", "rejectionReason": "Below the bar on system design." }
}

Status codes

Status	Meaning
`200`	Rejected; `step` is the now-rejected 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 rejected.
`429`	Rate limit exceeded.