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

# Candidate Interviews

> Create candidate interviews and manage interview invites

## Overview

Candidate interviews link candidates to interviews and handle the invite process. You can create candidate interviews and optionally send invites via email or SMS.

## Create Candidate Interview

Create a candidate interview and optionally send invite.

**Endpoint:** `POST /qsi/gather/candidate-interviews`

<ParamField name="candidateId" type="string" required>
  UUID of the candidate
</ParamField>

<ParamField name="interviewId" type="string" required>
  UUID of the interview
</ParamField>

<ParamField name="sendInvite" type="boolean">
  Whether to send invite immediately (default: false)
</ParamField>

<ParamField name="deliveryTypes" type="array">
  Delivery methods: `["email"]`, `["sms"]`, or `["email", "sms"]`
</ParamField>

<ParamField name="expiryDays" type="number">
  Days until invite expires (defaults to org setting)
</ParamField>

<ParamField name="externalId" type="string">
  Optional external ID for your system
</ParamField>

<ParamField name="externalRedirectUri" type="string">
  Optional redirect URL after interview completion
</ParamField>

<ParamField name="webhookUrl" type="string">
  Optional webhook URL for results notification
</ParamField>

<CodeGroup>
  ```json Request theme={null}
  {
    "candidateId": "uuid",
    "interviewId": "uuid",
    "sendInvite": true,
    "deliveryTypes": ["email", "sms"],
    "expiryDays": 7
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "id": "uuid",
      "candidateId": "uuid",
      "interviewId": "uuid",
      "status": "invite_sent",
      "inviteToken": "token",
      "expiry": "2024-01-08T00:00:00Z",
      "inviteSentAt": "2024-01-01T00:00:00Z"
    },
    "meta": {
      "requestId": "uuid",
      "timestamp": "2024-01-01T00:00:00Z"
    }
  }
  ```
</CodeGroup>

## Get Candidate Interview

Retrieve candidate interview details and status.

**Endpoint:** `GET /qsi/gather/candidate-interviews/{candidateInterviewId}`

<ParamField path="candidateInterviewId" type="string" required>
  UUID of the candidate interview
</ParamField>

<CodeGroup>
  ```json Response theme={null}
  {
    "data": {
      "id": "uuid",
      "candidateId": "uuid",
      "interviewId": "uuid",
      "status": "invite_sent",
      "inviteToken": "token",
      "expiry": "2024-01-08T00:00:00Z",
      "inviteSentAt": "2024-01-01T00:00:00Z",
      "externalId": "external-123",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    },
    "meta": {
      "requestId": "uuid",
      "timestamp": "2024-01-01T00:00:00Z"
    }
  }
  ```
</CodeGroup>

## List Candidate Interviews

List candidate interviews with filtering.

**Endpoint:** `GET /qsi/gather/candidate-interviews`

<ParamField query="candidateId" type="string">
  Filter by candidate ID
</ParamField>

<ParamField query="interviewId" type="string">
  Filter by interview ID
</ParamField>

<ParamField query="status" type="string">
  Filter by status
</ParamField>

<ParamField query="page" type="number">
  Page number (default: 1)
</ParamField>

<ParamField query="limit" type="number">
  Items per page (default: 50, max: 100)
</ParamField>

<CodeGroup>
  ```json Response theme={null}
  {
    "data": [
      {
        "id": "uuid",
        "candidateId": "uuid",
        "interviewId": "uuid",
        "status": "new_response",
        "inviteSentAt": "2024-01-01T00:00:00Z",
        "createdAt": "2024-01-01T00:00:00Z"
      }
    ],
    "meta": {
      "pagination": {
        "page": 1,
        "limit": 50,
        "total": 100,
        "totalPages": 2
      },
      "requestId": "uuid",
      "timestamp": "2024-01-01T00:00:00Z"
    }
  }
  ```
</CodeGroup>

### Status Values

* `invite_sent` - Invite has been sent to candidate
* `new_response` - Candidate has completed interview, awaiting review
* `has_reviewed` - Interview has been reviewed
* `partially_completed` - Interview partially completed
* `hired` - Candidate marked as hired
* `archived` - Candidate interview archived

## Update Candidate Interview Status

Update the status of a candidate interview.

**Endpoint:** `PATCH /qsi/gather/candidate-interviews/{candidateInterviewId}/status`

<ParamField path="candidateInterviewId" type="string" required>
  UUID of the candidate interview
</ParamField>

<ParamField name="status" type="string" required>
  New status value
</ParamField>

<CodeGroup>
  ```json Request theme={null}
  {
    "status": "has_reviewed"
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "id": "uuid",
      "status": "has_reviewed",
      "updatedAt": "2024-01-01T00:00:00Z"
    },
    "meta": {
      "requestId": "uuid",
      "timestamp": "2024-01-01T00:00:00Z"
    }
  }
  ```
</CodeGroup>

## Get Candidate Interview Results

Retrieve interview results including transcriptions, scores, ratings, summary, and score card results.

**Endpoint:** `GET /qsi/gather/candidate-interviews/{candidateInterviewId}/results`

<ParamField path="candidateInterviewId" type="string" required>
  UUID of the candidate interview
</ParamField>

<CodeGroup>
  ```json Response theme={null}
  {
    "data": {
      "candidateInterviewId": "uuid",
      "status": "new_response",
      "takenAt": "2024-01-01T00:00:00Z",
      "transcription": "Full interview transcription...",
      "audioUrl": "https://...",
      "score": 85,
      "averageRating": "4.5",
      "summary": "Candidate demonstrated strong technical skills...",
      "summaryStatus": "complete",
      "scoreCard": {
        "overallScore": 87.5,
        "overallExplanation": "Strong candidate with excellent technical skills...",
        "evaluationType": "ai_generated",
        "topicScores": [
          {
            "topic": "Technical Skills",
            "weight": 0.4,
            "confidence": 0.95,
            "explanation": "Demonstrated proficiency in required technologies",
            "evidence": [
              "Mentioned 5+ years experience with React",
              "Discussed complex state management patterns"
            ]
          },
          {
            "topic": "Communication",
            "weight": 0.3,
            "confidence": 0.88,
            "explanation": "Clear and articulate responses",
            "evidence": [
              "Explained technical concepts clearly",
              "Asked thoughtful questions"
            ]
          }
        ]
      },
      "responses": [
        {
          "questionId": "uuid",
          "questionTitle": "Tell me about yourself",
          "transcription": "Candidate response transcription...",
          "audioUrl": "https://..."
        }
      ],
      "shareLink": "https://..."
    },
    "meta": {
      "requestId": "uuid",
      "timestamp": "2024-01-01T00:00:00Z"
    }
  }
  ```
</CodeGroup>

<Callout type="info">
  **Summary Status**: The `summary` field may be `null` if not yet generated or
  if `summaryStatus` is `pre-summary-feature` or `error`. Valid `summaryStatus`
  values: `pre-summary-feature`, `processing`, `complete`, `error`.
</Callout>

<Callout type="info">
  **Score Cards**: The `scoreCard` field may be `null` if score cards feature is
  not enabled or evaluation not yet generated. `evaluationType` values:
  `ai_generated`, `manual`, `hybrid`.
</Callout>

## Resend Invite

Resend an invite to a candidate.

**Endpoint:** `POST /qsi/gather/candidate-interviews/{candidateInterviewId}/resend-invite`

<ParamField path="candidateInterviewId" type="string" required>
  UUID of the candidate interview
</ParamField>

<ParamField name="deliveryTypes" type="array">
  Delivery methods: `["email"]`, `["sms"]`, or `["email", "sms"]`
</ParamField>

<CodeGroup>
  ```json Request theme={null}
  {
    "deliveryTypes": ["email"]
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "id": "uuid",
      "inviteSentAt": "2024-01-01T00:00:00Z",
      "status": "invite_sent"
    },
    "meta": {
      "requestId": "uuid",
      "timestamp": "2024-01-01T00:00:00Z"
    }
  }
  ```
</CodeGroup>

## Delivery Types

### Email

Sends invite via email with a link to start the interview.

### SMS

Sends invite via SMS with a link to start the interview.

<Callout type="info">
  You can send invites via email, SMS, or both. Ensure the candidate has opted
  in for SMS if using SMS delivery.
</Callout>

## Related Resources

<CardGroup cols={2}>
  <Card title="Candidates" icon="user" href="/api-reference/candidates">
    Learn about managing candidates
  </Card>

  <Card title="Interviews" icon="file-text" href="/api-reference/interviews">
    Learn about creating interviews
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/webhooks">
    Set up webhooks for interview completion notifications
  </Card>

  <Card title="Sending Invites" icon="mail" href="/guides/sending-invites">
    Guide on sending interview invites
  </Card>
</CardGroup>