Skip to main content

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.

​
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
}

​
Get Candidate Interview

Retrieve candidate interview details and status. Endpoint: GET /qsi/gather/candidate-interviews/{candidateInterviewId}
​
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
​
candidateId
string
Filter by candidate ID
​
interviewId
string
Filter by interview ID
​
status
string
Filter by status
​
page
number
Page number (default: 1)
​
limit
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
​
candidateInterviewId
string
required
UUID of the candidate interview
{
  "status": "has_reviewed"
}

​
Get Candidate Interview Results

Retrieve interview results including transcriptions, scores, ratings, summary, and score card results. Endpoint: GET /qsi/gather/candidate-interviews/{candidateInterviewId}/results
​
candidateInterviewId
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
​
candidateInterviewId
string
required
UUID of the candidate interview
{
  "deliveryTypes": ["email"]
}

​
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