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

# Update a Candidate

> Rename a Candidate, move their stage, or add notes.

Use the Edit Interview API to update a Candidate's interview from your own system, for example to rename the Candidate, move them to a custom stage, or add notes.

> [!NOTE]
>
> **Rate limit:** 60 requests per minute per API key. Requests over the limit return `429 Too Many Requests`.

## Request body fields

**interviewId** `string` *required*

The UUID of the interview to update.

**candidateName** `string`

The Candidate's name. Must contain 1–255 characters.

**candidateEmail** `string`

The Candidate's email address. At least 5 characters, no spaces. Stored in lowercase.

**expiryDateInMillis** `number`

New invitation expiry time, as a Unix timestamp in milliseconds.

**viewStatus** `string`

`new` or `viewed`.

**status** `string`

A stage configured in your Company's **Custom Stages** settings. 1–80 characters.

**customQuestions** `object[]`

Replacement custom interview questions. Each item requires `question`. `evaluationCriteria` is optional; when you include it, `lookingFor`, `strongAnswer`, `weakAnswer`, `weight` (1–10) and `maxFollowup` (0–2) are required.

**candidateAdditionalFields** `object`

Replacement values for configured Candidate additional fields.

**recruiterNotes** `string`

Internal notes, up to 5,000 characters.

At least one optional field should be included. Sending a `status` that is not configured as a custom stage returns `400 Bad Request` with "Only stages in your hiring pipeline can be selected for status updates".

```bash cURL theme={null}
curl -X PUT "https://api.interviewflowai.com/api/external/interview" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key_here" \
  -d '{
    "interviewId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "candidateName": "Taylor Morgan",
    "status": "Technical Review",
    "recruiterNotes": "Strong systems design experience."
  }'
```

## Response

```json 200 theme={null}
{
  "code": 200,
  "message": "Interview updated successfully"
}
```

The API key must belong to the same Company as the interview. A missing interview or an interview owned by another Company returns `404 Not Found`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.