Interviews - Humanly Developer Docs

Overview

Interviews define the structure and content of phone interviews. You can create standard interviews with audio questions or questionnaire-type interviews with survey questions.

Interview status is represented as a numeric value: 0 = Active, 1 = Paused, 2 = Closed, 3 = Archived.

Need to update multiple interviews at once? See the Bulk Update Interviews endpoint.

Create Interview

Create a new interview. The API supports standard interviews and fully-configured ai_interviewer interviews. Endpoint: POST /qsi/gather/interviews

Questionnaire-type interviews must be created through the Qualifi dashboard.

AI Interviewer fields

These apply when interviewType is "ai_interviewer". The AI persona is generated automatically from the configuration and regenerated when behavior changes; internal persona identifiers and prompts are never returned.

cURL
JavaScript
Python

curl -X POST https://api.prod.qualifi.hr/qsi/gather/interviews \
  -H "x-api-key: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Software Engineer Interview",
    "displayName": "Software Engineer Interview",
    "interviewType": "standard",
    "questionIds": ["uuid1", "uuid2"],
    "surveyQuestions": [
      { "id": "survey-q-uuid", "knockout": false }
    ],
    "keywords": ["javascript", "react"],
    "language": "en"
  }'

const response = await fetch('https://api.prod.qualifi.hr/qsi/gather/interviews', {
  method: 'POST',
  headers: {
    'x-api-key': apiKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Software Engineer Interview',
    displayName: 'Software Engineer Interview',
    interviewType: 'standard',
    questionIds: ['uuid1', 'uuid2'],
    surveyQuestions: [
      { id: 'survey-q-uuid', knockout: false }
    ],
    keywords: ['javascript', 'react'],
    language: 'en'
  })
});
const interview = await response.json();

response = requests.post(
    'https://api.prod.qualifi.hr/qsi/gather/interviews',
    headers={
        'x-api-key': api_key,
        'Content-Type': 'application/json'
    },
    json={
        'title': 'Software Engineer Interview',
        'displayName': 'Software Engineer Interview',
        'interviewType': 'standard',
        'questionIds': ['uuid1', 'uuid2'],
        'surveyQuestions': [
            {'id': 'survey-q-uuid', 'knockout': False}
        ],
        'keywords': ['javascript', 'react'],
        'language': 'en'
    }
)
interview = response.json()

{
  "title": "Software Engineer Interview",
  "displayName": "Software Engineer Interview",
  "interviewType": "standard",
  "description": "Technical interview for software engineering role",
  "language": "en",
  "questionIds": ["uuid1", "uuid2"],
  "surveyQuestions": [
    { "id": "survey-q-uuid", "knockout": false }
  ],
  "keywords": ["javascript", "react"]
}

{
  "data": {
    "interview": {
      "id": "interview-uuid",
      "title": "Software Engineer Interview",
      "displayName": "Software Engineer Interview",
      "interviewType": "standard",
      "status": 0,
      "description": "Technical interview for software engineering role",
      "language": "en",
      "resume": false,
      "webOnly": false,
      "messageGroupId": "msg-group-uuid",
      "narratorId": "narrator-uuid",
      "organizationId": "org-uuid",
      "teamId": "team-uuid",
      "createdById": "user-uuid",
      "createdAt": "2026-01-15T00:00:00Z",
      "updatedAt": "2026-01-15T00:00:00Z"
    }
  },
  "meta": {
    "requestId": "req-uuid",
    "timestamp": "2026-01-15T00:00:00Z"
  }
}

Create an AI Interviewer

Set interviewType: "ai_interviewer" and provide an aiConfiguration. The persona is generated server-side.

{
  "title": "AI Screen — Backend Engineer",
  "displayName": "AI Screen",
  "interviewType": "ai_interviewer",
  "language": "en",
  "aiTextQuestionIds": ["ai-text-question-uuid"],
  "jobDescriptionText": "We are hiring a senior backend engineer...",
  "knowledgeBaseIds": ["kb-uuid"],
  "scoreCardTopics": [
    {
      "topic": "System Design",
      "weight": 60,
      "lookingFor": ["Scalability", "Trade-off analysis"],
      "scoreDescriptions": {
        "level1": "Limited system design ability",
        "level3": "Adequate system design ability",
        "level5": "Exceptional system design ability"
      }
    }
  ],
  "aiConfiguration": {
    "replicaId": "replica-uuid",
    "friendlyTone": true,
    "professionalTone": true,
    "askFollowUpQuestions": true,
    "callRecording": true,
    "closedCaptions": true,
    "captureResponses": true,
    "language": "en",
    "timeoutSeconds": 1800
  }
}

{
  "data": {
    "interview": {
      "id": "interview-uuid",
      "title": "AI Screen — Backend Engineer",
      "displayName": "AI Screen",
      "interviewType": "ai_interviewer",
      "status": 0,
      "language": "en",
      "resume": false,
      "webOnly": false,
      "organizationId": "org-uuid",
      "teamId": "team-uuid",
      "createdById": "user-uuid",
      "createdAt": "2026-06-16T00:00:00Z",
      "updatedAt": "2026-06-16T00:00:00Z",
      "audioOnly": false,
      "replicaId": "replica-uuid",
      "aiConfiguration": {
        "askFollowUpQuestions": true,
        "askToElaborate": false,
        "digDeeper": false,
        "friendlyTone": true,
        "professionalTone": true,
        "conversationalStyle": true,
        "audioOnly": false,
        "greetingMessage": null,
        "closedCaptions": true,
        "callRecording": true,
        "captureResponses": true,
        "askCandidateQuestions": false,
        "language": "en",
        "timeoutSeconds": 1800,
        "coachingType": null,
        "coachingSubType": null,
        "conversationalContext": "Interview for AI Screen — Backend Engineer...",
        "replicaId": "replica-uuid",
        "replica": {
          "id": "replica-uuid",
          "name": "Avatar",
          "photoUrl": "https://example.com/avatar.png",
          "replicaId": "replica-ext-id"
        }
      }
    }
  },
  "meta": {
    "requestId": "req-uuid",
    "timestamp": "2026-06-16T00:00:00Z"
  }
}

For ai_interviewer interviews, GET /qsi/gather/interviews/{interviewId} and PATCH return the same nested aiConfiguration object (including the read-only conversationalContext). To update behavior, send an aiConfiguration on PATCH — the persona is regenerated automatically.

Get Interview

Retrieve interview details including questions. Endpoint: GET /qsi/gather/interviews/{interviewId}

interviewId

string

required

UUID of the interview

teamId

string

Override the team context for this request

{
  "data": {
    "interview": {
      "id": "interview-uuid",
      "title": "Software Engineer Interview",
      "displayName": "Software Engineer Interview",
      "interviewType": "standard",
      "status": 0,
      "description": "Technical interview for software engineering role",
      "descriptionUrl": "https://example.com/job-description",
      "language": "en",
      "resume": true,
      "webOnly": false,
      "messageGroupId": "msg-group-uuid",
      "narratorId": "narrator-uuid",
      "organizationId": "org-uuid",
      "teamId": "team-uuid",
      "createdById": "user-uuid",
      "createdAt": "2026-01-15T00:00:00Z",
      "updatedAt": "2026-01-15T00:00:00Z"
    }
  },
  "meta": {
    "requestId": "req-uuid",
    "timestamp": "2026-01-15T00:00:00Z"
  }
}

List Interviews

List all interviews with pagination and filtering. Endpoint: GET /qsi/gather/interviews

page

number

Page number (default: 1)

pageSize

number

Items per page

string

Search interviews by title

archived

boolean

Include archived interviews (default: false)

interviewType

string

Filter by type: "standard" or "questionnaire"

{
  "data": {
    "interviews": [
      {
        "id": "interview-uuid",
        "title": "Software Engineer Interview",
        "displayName": "Software Engineer Interview",
        "interviewType": "standard",
        "status": 0,
        "description": "Technical interview for software engineering role",
        "language": "en",
        "resume": false,
        "webOnly": false,
        "messageGroupId": "msg-group-uuid",
        "organizationId": "org-uuid",
        "teamId": "team-uuid",
        "createdById": "user-uuid",
        "createdAt": "2026-01-15T00:00:00Z",
        "updatedAt": "2026-01-15T00:00:00Z"
      }
    ],
    "pagination": {
      "total": 42,
      "page": 1,
      "pages": 5,
      "pageSize": 10
    }
  },
  "meta": {
    "requestId": "req-uuid",
    "timestamp": "2026-01-15T00:00:00Z"
  }
}

Update Interview

Update interview properties including questions, keywords, and settings. Endpoint: PATCH /qsi/gather/interviews/{interviewId}

interviewId

string

required

UUID of the interview to update

{
  "title": "Updated Interview Title",
  "questionIds": ["uuid1", "uuid2", "uuid3"],
  "surveyQuestions": [
    { "id": "survey-q-uuid", "knockout": true }
  ],
  "keywords": ["python", "django"],
  "removedKeywords": ["php"]
}

{
  "data": {
    "interview": {
      "id": "interview-uuid",
      "title": "Updated Interview Title",
      "displayName": "Software Engineer Interview",
      "interviewType": "standard",
      "status": 0,
      "description": "Technical interview for software engineering role",
      "language": "en",
      "resume": false,
      "webOnly": false,
      "messageGroupId": "msg-group-uuid",
      "narratorId": "narrator-uuid",
      "organizationId": "org-uuid",
      "teamId": "team-uuid",
      "createdById": "user-uuid",
      "createdAt": "2026-01-15T00:00:00Z",
      "updatedAt": "2026-01-16T00:00:00Z"
    }
  },
  "meta": {
    "requestId": "req-uuid",
    "timestamp": "2026-01-16T00:00:00Z"
  }
}

Delete Interview

Archive an interview. Endpoint: DELETE /qsi/gather/interviews/{interviewId}

interviewId

string

required

UUID of the interview to archive

teamId

string

Override the team context for this request

userId

string

User performing the archive action

{
  "data": {
    "interview": {
      "id": "interview-uuid",
      "title": "Software Engineer Interview",
      "displayName": "Software Engineer Interview",
      "interviewType": "standard",
      "status": 3,
      "language": "en",
      "resume": false,
      "webOnly": false,
      "organizationId": "org-uuid",
      "teamId": "team-uuid",
      "createdById": "user-uuid",
      "createdAt": "2026-01-15T00:00:00Z",
      "updatedAt": "2026-02-01T00:00:00Z",
      "archivedAt": "2026-02-01T00:00:00Z"
    }
  },
  "meta": {
    "requestId": "req-uuid",
    "timestamp": "2026-02-01T00:00:00Z"
  }
}

Copy Interview

Copy an interview template to a different team (or the same team with a “(copy)” suffix). The copied interview includes all questions, survey questions, AI text questions, keywords (optional), score card templates, and AI interview configurations. Endpoint: POST /qsi/gather/interviews/{interviewId}/copy

interviewId

string

required

UUID of the interview to copy

cURL
JavaScript
Python

curl -X POST https://api.prod.qualifi.hr/qsi/gather/interviews/{interviewId}/copy \
  -H "x-api-key: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "teamId": "target-team-uuid",
    "copyKeywords": false
  }'

const response = await fetch(
  `https://api.prod.qualifi.hr/qsi/gather/interviews/${interviewId}/copy`,
  {
    method: 'POST',
    headers: {
      'x-api-key': apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      teamId: 'target-team-uuid',
      copyKeywords: false
    })
  }
);
const interview = await response.json();

response = requests.post(
    f'https://api.prod.qualifi.hr/qsi/gather/interviews/{interview_id}/copy',
    headers={
        'x-api-key': api_key,
        'Content-Type': 'application/json'
    },
    json={
        'teamId': 'target-team-uuid',
        'copyKeywords': False
    }
)
interview = response.json()

{
  "teamId": "target-team-uuid",
  "copyKeywords": false,
  "messageGroupId": "message-group-uuid"
}

{
  "data": {
    "interview": {
      "id": "copied-interview-uuid",
      "title": "Engineering Interview",
      "displayName": "Engineering Interview",
      "interviewType": "standard",
      "status": 0,
      "description": "Interview for engineering candidates",
      "language": "en",
      "resume": true,
      "webOnly": false,
      "messageGroupId": "message-group-uuid",
      "organizationId": "org-uuid",
      "teamId": "target-team-uuid",
      "createdById": "user-uuid",
      "createdAt": "2026-01-15T00:00:00Z",
      "updatedAt": "2026-01-15T00:00:00Z"
    }
  },
  "meta": {
    "requestId": "req-uuid",
    "timestamp": "2026-01-15T00:00:00Z"
  }
}

Copy Behavior

Questions:

Different Team: Questions are copied as new questions in the target team
Same Team: Questions are reused (not duplicated)

Survey Questions:

Different Team: Survey questions are copied with all options and preferred options
Same Team: Survey questions are reused

AI Text Questions:

Different Team: AI text questions are copied as new questions
Same Team: AI text questions are reused

Keywords:

Only copied if copyKeywords: true
Creates new keyword associations for the copied interview

Score Card Templates:

All score card templates are copied to the new interview

AI Interview Configuration:

For AI interviews, a new AI interviewer persona is created
AI configuration is copied with the new persona ID
Original persona is not modified

MessageGroup:

If messageGroupId is provided, it will be used
If not provided, the default message group for the interview type will be used

When copying to the same team, the interview title will automatically have “(copy)” appended to avoid conflicts.

Interview Types

Standard Interviews

Standard interviews use audio questions that are played to candidates during phone calls.

Questionnaire Interviews

Questionnaire interviews use survey questions that candidates answer via web interface.

You can mix question types in standard interviews, but questionnaire-type interviews are specifically designed for survey-style questions.

Questions

Learn about creating questions for interviews

Candidate Interviews

Send interview invites to candidates

Bulk Update Interviews

Update multiple interviews in a single request

​Overview

​Create Interview

​AI Interviewer fields

​Create an AI Interviewer

​Get Interview

​List Interviews

​Update Interview

​Delete Interview

​Copy Interview

​Copy Behavior

​Interview Types

​Standard Interviews

​Questionnaire Interviews

​Related Resources

Questions

Candidate Interviews

Bulk Update Interviews

Overview

Create Interview

AI Interviewer fields

Create an AI Interviewer

Get Interview

List Interviews

Update Interview

Delete Interview

Copy Interview

Copy Behavior

Interview Types

Standard Interviews

Questionnaire Interviews

Related Resources