Candidate Interviews

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

{
  "candidateId": "uuid",
  "interviewId": "uuid",
  "sendInvite": true,
  "deliveryTypes": ["email", "sms"],
  "expiryDays": 7
}

{
  "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"
  }
}

Get Candidate Interview

Retrieve candidate interview details and status. Endpoint: GET /qsi/gather/candidate-interviews/{candidateInterviewId}

string

required

UUID of the candidate interview

{
  "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"
  }
}

List Candidate Interviews

List candidate interviews with filtering. Endpoint: GET /qsi/gather/candidate-interviews

string

Filter by candidate ID

string

Filter by interview ID

string

Filter by status

number

Page number (default: 1)

number

Items per page (default: 50, max: 100)

{
  "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"
  }
}

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

string

required

UUID of the candidate interview

{
  "status": "has_reviewed"
}

{
  "data": {
    "id": "uuid",
    "status": "has_reviewed",
    "updatedAt": "2024-01-01T00:00:00Z"
  },
  "meta": {
    "requestId": "uuid",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

Get Candidate Interview Results

Retrieve interview results including transcriptions, scores, ratings, summary, and score card results. Endpoint: GET /qsi/gather/candidate-interviews/{candidateInterviewId}/results

string

required

UUID of the candidate interview

{
  "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"
  }
}

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.

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.

Resend Invite

Resend an invite to a candidate. Endpoint: POST /qsi/gather/candidate-interviews/{candidateInterviewId}/resend-invite

string

required

UUID of the candidate interview

{
  "deliveryTypes": ["email"]
}

{
  "data": {
    "id": "uuid",
    "inviteSentAt": "2024-01-01T00:00:00Z",
    "status": "invite_sent"
  },
  "meta": {
    "requestId": "uuid",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

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.

You can send invites via email, SMS, or both. Ensure the candidate has opted in for SMS if using SMS delivery.

Candidates

Learn about managing candidates

Interviews

Learn about creating interviews

Webhooks

Set up webhooks for interview completion notifications

Sending Invites

Guide on sending interview invites

Get Started

API Reference

Guides

Code Examples

Resources

Overview

Create Candidate Interview

Get Candidate Interview

List Candidate Interviews

Status Values

Update Candidate Interview Status

Get Candidate Interview Results

Resend Invite

Delivery Types

Email

SMS

Candidates

Interviews

Webhooks

Sending Invites

​Overview

​Create Candidate Interview

​Get Candidate Interview

​List Candidate Interviews

​Status Values

​Update Candidate Interview Status

​Get Candidate Interview Results

​Resend Invite

​Delivery Types

​Email

​SMS

​Related Resources

Candidates

Interviews

Webhooks

Sending Invites

Overview

Create Candidate Interview

Get Candidate Interview

List Candidate Interviews

Status Values

Update Candidate Interview Status

Get Candidate Interview Results

Resend Invite

Delivery Types

Email

SMS

Related Resources