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

# Update candidate

> Update a candidate — partial update, send only the fields you want to change

Send only the fields you want to change. All fields except `candidate_id` are optional.

## Authentication

<ResponseField name="Authorization" type="string" required>
  Bearer authentication header of the form `Bearer <token>`, where `<token>` is your API token.
</ResponseField>

## Request Body

<ParamField body="candidate_id" type="string" required placeholder="Candidate UUID">
  The candidate to update.
</ParamField>

<ParamField body="status" type="string">
  New pipeline status. One of: `applied` `screening` `phone_screen` `interview` `technical` `offer` `hired` `rejected` `withdrawn` `on_hold` `shortlisted` `qualified` `uploaded`.
</ParamField>

<ParamField body="tags" type="string[]">
  Array of free-form tags. Replaces the existing tag list.
</ParamField>

<ParamField body="pool_stage" type="string">
  Talent-pool stage. One of: `cold` `warm` `hot` `not_interested`. Pass `null` to clear.
</ParamField>

<ParamField body="note_to_candidate" type="string">
  Recruiter note attached to the candidate (used in follow-up emails). Pass `null` to clear.
</ParamField>

<Info>
  At least one field beyond `candidate_id` must be provided. Otherwise the response is `400 At least one updatable field must be provided`.
</Info>

<RequestExample>
  ```bash cURL theme={null}
  curl --location --request PATCH 'https://api.hirempire.com/v1/update-candidate' \
  --header 'Authorization: Bearer sk-••••••••••••' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "candidate_id": "8fc4ea3c-ecc4-4a92-96fd-a14436a79a1b",
      "status": "rejected"
  }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.hirempire.com/v1/update-candidate', {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer sk-••••••••••••',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      candidate_id: "8fc4ea3c-ecc4-4a92-96fd-a14436a79a1b",
      status: "rejected"
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.hirempire.com/v1/update-candidate"
  headers = {
      "Authorization": "Bearer sk-••••••••••••",
      "Content-Type": "application/json"
  }
  payload = {
      "candidate_id": "8fc4ea3c-ecc4-4a92-96fd-a14436a79a1b",
      "status": "rejected"
  }

  response = requests.patch(url, headers=headers, json=payload)
  print(response.json())
  ```

  ```php PHP theme={null}
  <?php
  $curl = curl_init();

  $payload = json_encode([
      "candidate_id" => "8fc4ea3c-ecc4-4a92-96fd-a14436a79a1b",
      "status" => "rejected"
  ]);

  curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://api.hirempire.com/v1/update-candidate',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'PATCH',
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_HTTPHEADER => array(
      'Authorization: Bearer sk-••••••••••••',
      'Content-Type: application/json'
    ),
  ));

  $response = curl_exec($curl);
  curl_close($curl);

  print_r(json_decode($response, true));
  ?>
  ```
</RequestExample>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the candidate status was updated successfully
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier of the updated candidate
</ResponseField>

<ResponseField name="status" type="string">
  The new pipeline status of the candidate
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "id": "8fc4ea3c-ecc4-4a92-96fd-a14436a79a1b",
    "status": "rejected"
  }
  ```
</ResponseExample>

## Error Responses

### 400 Bad Request

```json theme={null}
{
  "success": false,
  "error": "candidate_id is required and must be a UUID"
}
```

```json theme={null}
{
  "success": false,
  "error": "status is required"
}
```

```json theme={null}
{
  "success": false,
  "error": "status must be one of: applied, screening, phone_screen, interview, technical, offer, hired, rejected, withdrawn, on_hold, shortlisted, qualified, uploaded"
}
```

### 401 Unauthorized

```json theme={null}
{
  "success": false,
  "error": "Invalid token"
}
```

```json theme={null}
{
  "success": false,
  "error": "Invalid candidate id"
}
```