> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kalent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Update candidate status

> Change the status of a candidate in a sourcing.

<Card title="First time? Set up Authentication" icon="key" href="/authentication">
  Learn how to authenticate your API requests with your API key.
</Card>

Updates the status of a candidate in your workspace. The `statusHandle` must be a global status (`TO_BE_CONTACTED`, `CONTACTED`, `NOT_RETAINED`, `OUTREACH_SEQUENCE_STARTED`) or a custom status defined in your workspace. Setting the status to `NOT_RETAINED` removes the candidate from the active pipeline and cancels any active outreach tasks.

## Path parameters

<ParamField path="candidateId" type="string" required>
  The candidate id (from [Get candidates](/api-reference/get-candidates) or [Add talent to sourcing](/api-reference/add-talent-to-sourcing)).
</ParamField>

## Request body

<ParamField body="statusHandle" type="string" required>
  The target status handle.
</ParamField>

## Response

When `success` is `true`, `data` includes `candidateId`, `talentId`, `sourcingId`, `statusHandle`, and `updatedAt`.

## Errors

| Code                 | HTTP |
| -------------------- | ---- |
| `validation_error`   | 400  |
| `not_found`          | 404  |
| `method_not_allowed` | 405  |
| `internal_error`     | 500  |

```bash theme={null}
curl -X PATCH https://app.kalent.ai/api/v1/candidates/CANDIDATE_ID/status \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"statusHandle":"CONTACTED"}'
```