# Reject a candidate

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

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).

<Notice type="info" title="No email">
A v1 reject sends **no email**. Activity is logged and the organization status cache is synced.
</Notice>

## 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

```bash
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`

```json
{
  "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. |