Questions

Overview

The Gather API supports three types of questions, each designed for different interview formats:

Audio Questions - Questions with text scripts that can be automatically converted to audio using text-to-speech (TTS) technology. These are used in standard video interviews where candidates record video responses to audio prompts.
Survey Questions - Multiple choice, yes/no, thumbs up/down, or free text questions used for screening and questionnaires. These can be added to interviews or used in standalone surveys. Perfect for pre-screening candidates or gathering structured feedback.
AI Text Questions - Text-based questions used in AI-powered interviews where candidates provide written responses that are evaluated by AI. Ideal for technical assessments and written evaluations.

Audio Questions

Audio questions are the building blocks of standard video interviews. You can create questions with text scripts that can be automatically converted to audio using text-to-speech (TTS) technology.

Create Audio Question

Create a new audio question with optional TTS audio generation. Endpoint: POST /qsi/gather/questions

cURL
JavaScript
Python

curl -X POST https://api.prod.qualifi.hr/qsi/gather/questions \
  -H "x-api-key: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Tell me about yourself",
    "description": "A standard introductory question",
    "audioURL": "https://example.com/audio/question1.mp3",
    "narratorId": "narrator-uuid",
    "questionScript": "Tell me about yourself and your background."
  }'

const response = await fetch('https://api.prod.qualifi.hr/qsi/gather/questions', {
  method: 'POST',
  headers: {
    'x-api-key': apiKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Tell me about yourself',
    description: 'A standard introductory question',
    audioURL: 'https://example.com/audio/question1.mp3',
    narratorId: 'narrator-uuid',
    questionScript: 'Tell me about yourself and your background.'
  })
});
const question = await response.json();

response = requests.post(
    'https://api.prod.qualifi.hr/qsi/gather/questions',
    headers={
        'x-api-key': api_key,
        'Content-Type': 'application/json'
    },
    json={
        'title': 'Tell me about yourself',
        'description': 'A standard introductory question',
        'audioURL': 'https://example.com/audio/question1.mp3',
        'narratorId': 'narrator-uuid',
        'questionScript': 'Tell me about yourself and your background.'
    }
)
question = response.json()

{
  "title": "Tell me about yourself",
  "description": "A standard introductory question",
  "audioURL": "https://example.com/audio/question1.mp3",
  "narratorId": "narrator-uuid",
  "questionScript": "Tell me about yourself and your background."
}

The userId field is optional. If not provided, it will be resolved from your API credential. If you need to specify a different user as the creator, provide the userId field.

Audio Source: You must provide either:

audioURL (pre-recorded audio), OR
questionScript + narratorId (for automatic TTS generation)

Do not provide both audioURL and questionScript - if audioURL is provided, it will be used and questionScript/narratorId will be ignored.

List Audio Questions

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

page

number

Page number (0-indexed, default: 0)

pageSize

number

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

archived

boolean

Filter by archived status (true, false, or omit for all)

string

Search term to filter by title/description

teamId

string

Optional override for team ID. If not provided, will be resolved from your API credential (teamId or defaultTeamId). Required if using an organization-level API key without a defaultTeamId.

cURL
JavaScript
Python

curl -X GET "https://api.prod.qualifi.hr/qsi/gather/questions?page=0&pageSize=50&archived=false" \
  -H "x-api-key: ${API_KEY}"

const params = new URLSearchParams({
  page: '0',
  pageSize: '50',
  archived: 'false'
});

const response = await fetch(
  `https://api.prod.qualifi.hr/qsi/gather/questions?${params}`,
  {
    headers: {
      'x-api-key': apiKey
    }
  }
);
const data = await response.json();

params = {
    'page': 0,
    'pageSize': 50,
    'archived': False
}
response = requests.get(
    'https://api.prod.qualifi.hr/qsi/gather/questions',
    headers={'x-api-key': api_key},
    params=params
)
data = response.json()

{
  "data": {
    "questions": [
      {
        "id": "question-uuid",
        "title": "Tell me about yourself",
        "audioURL": "https://example.com/audio/question1.mp3",
        "description": "A standard introductory question",
        "narratorId": "narrator-uuid",
        "questionScript": "Tell me about yourself and your background.",
        "organizationId": "org-uuid",
        "teamId": "team-uuid",
        "createdById": "user-uuid",
        "createdAt": "2024-01-01T00:00:00Z",
        "updatedAt": "2024-01-01T00:00:00Z",
        "archivedAt": null
      }
    ],
    "pagination": {
      "total": 100,
      "page": 0,
      "pages": 2,
      "pageSize": 50
    }
  },
  "meta": {
    "requestId": "uuid",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

Get Audio Question

Retrieve a specific audio question by ID. Endpoint: GET /qsi/gather/questions/{questionId}

questionId

string

required

UUID of the question to retrieve

teamId

string

Optional override for team ID. If not provided, will be resolved from your API credential (teamId or defaultTeamId). Required if using an organization-level API key without a defaultTeamId.

cURL
JavaScript
Python

curl -X GET https://api.prod.qualifi.hr/qsi/gather/questions/{questionId} \
  -H "x-api-key: ${API_KEY}"

const response = await fetch(
  `https://api.prod.qualifi.hr/qsi/gather/questions/${questionId}`,
  {
    headers: {
      'x-api-key': apiKey
    }
  }
);
const question = await response.json();

response = requests.get(
    f'https://api.prod.qualifi.hr/qsi/gather/questions/{question_id}',
    headers={'x-api-key': api_key}
)
question = response.json()

{
  "data": {
    "question": {
      "id": "question-uuid",
      "title": "Tell me about yourself",
      "audioURL": "https://example.com/audio/question1.mp3",
      "description": "A standard introductory question",
      "narratorId": "narrator-uuid",
      "questionScript": "Tell me about yourself and your background.",
      "organizationId": "org-uuid",
      "teamId": "team-uuid",
      "createdById": "user-uuid",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z",
      "archivedAt": null
    }
  },
  "meta": {
    "requestId": "uuid",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

Update Audio Question

Update audio question properties. Only include fields you want to update. Endpoint: PATCH /qsi/gather/questions/{questionId}

questionId

string

required

UUID of the question to update

{
  "title": "Updated question title",
  "questionScript": "Updated script text"
}

Archive Audio Question

Archive an audio question (soft delete). Endpoint: DELETE /qsi/gather/questions/{questionId}

questionId

string

required

UUID of the question to archive

userId

string

User ID for the archive action. If not provided, will be resolved from API credential.

{
  "data": {
    "question": {
      "id": "question-uuid",
      "archivedAt": "2024-01-01T00:00:00Z"
    }
  },
  "meta": {
    "requestId": "uuid",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

Survey Questions

Survey questions are used for screening and questionnaires. They support multiple question types including multiple choice, yes/no, thumbs up/down, and free text.

Survey Question Types

The following question types are supported:

FREE_TEXT - Free text response with optional character limit. Use maxCharacterLength to set limits.
YES_NO - Yes/No question with optional preferred option. Use preferredOption to mark the preferred answer.
THUMBS_UP_DOWN - Thumbs up/down question. Requires options array with two options.
MULTIPLE_CHOICE - Single answer multiple choice question. Requires options array.
MULTIPLE_CHOICE_WEIGHTED - Multiple choice with weighted scoring. Requires options array with weights.
MULTIPLE_CHOICE_MULTIPLE_ANSWER - Multiple choice allowing multiple selections. Requires options array. Use selectAllForFullScore to require all options for full score.

Create Survey Question

Create a new survey question. Endpoint: POST /qsi/gather/survey-questions

{
  "type": "FREE_TEXT",
  "title": "Tell us about your experience",
  "includeScoring": true,
  "maxCharacterLength": 500
}

{
  "type": "YES_NO",
  "title": "Do you have 5+ years of experience?",
  "includeScoring": true,
  "knockout": false,
  "preferredOption": true
}

{
  "type": "MULTIPLE_CHOICE",
  "title": "What is your preferred work style?",
  "includeScoring": true,
  "knockout": false,
  "options": [
    {
      "title": "Remote",
      "preferred": true,
      "weight": 5,
      "ordinal": 1
    },
    {
      "title": "Hybrid",
      "weight": 3,
      "ordinal": 2
    },
    {
      "title": "On-site",
      "weight": 1,
      "ordinal": 3
    }
  ]
}

{
  "type": "THUMBS_UP_DOWN",
  "title": "Would you recommend this candidate?",
  "includeScoring": true,
  "knockout": false,
  "options": [
    {
      "title": "Thumbs Up",
      "preferred": true,
      "weight": 5,
      "ordinal": 1
    },
    {
      "title": "Thumbs Down",
      "weight": 1,
      "ordinal": 2
    }
  ]
}

{
  "type": "MULTIPLE_CHOICE_WEIGHTED",
  "title": "Rate your experience level",
  "includeScoring": true,
  "options": [
    {
      "title": "Expert",
      "weight": 5,
      "ordinal": 1
    },
    {
      "title": "Advanced",
      "weight": 4,
      "ordinal": 2
    },
    {
      "title": "Intermediate",
      "weight": 3,
      "ordinal": 3
    }
  ]
}

{
  "type": "MULTIPLE_CHOICE_MULTIPLE_ANSWER",
  "title": "Select all that apply",
  "includeScoring": true,
  "selectAllForFullScore": true,
  "options": [
    {
      "title": "Option 1",
      "weight": 2,
      "ordinal": 1
    },
    {
      "title": "Option 2",
      "weight": 2,
      "ordinal": 2
    }
  ]
}

{
  "type": "MULTIPLE_CHOICE",
  "title": "What is your preferred work style?",
  "includeScoring": true,
  "options": [
    {
      "title": "Remote",
      "preferred": true,
      "weight": 5,
      "ordinal": 1
    },
    {
      "title": "Hybrid",
      "weight": 3,
      "ordinal": 2
    }
  ]
}

List Survey Questions

List survey questions with pagination and filtering. Endpoint: GET /qsi/gather/survey-questions

page

number

Page number (0-indexed, default: 0)

pageSize

number

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

string

Search term to filter by title (case-insensitive)

archived

boolean

Filter by archived status (true, false, or omit for all)

teamId

string

Optional override for team ID. If not provided, will be resolved from your API credential (teamId or defaultTeamId). Required if using an organization-level API key without a defaultTeamId.

cURL
JavaScript
Python

curl -X GET "https://api.prod.qualifi.hr/qsi/gather/survey-questions?page=0&pageSize=50" \
  -H "x-api-key: ${API_KEY}"

const params = new URLSearchParams({
  page: '0',
  pageSize: '50'
});

const response = await fetch(
  `https://api.prod.qualifi.hr/qsi/gather/survey-questions?${params}`,
  {
    headers: {
      'x-api-key': apiKey
    }
  }
);
const data = await response.json();

params = {
    'page': 0,
    'pageSize': 50
}
response = requests.get(
    'https://api.prod.qualifi.hr/qsi/gather/survey-questions',
    headers={'x-api-key': api_key},
    params=params
)
data = response.json()

{
  "data": {
    "surveyQuestions": [
      {
        "id": "survey-question-uuid-1",
        "title": "Rate your experience",
        "type": "MULTIPLE_CHOICE",
        "organizationId": "org-uuid",
        "teamId": "team-uuid",
        "supportingVideoURL": null,
        "maxCharacterLength": null,
        "includeScoring": true,
        "selectAllForFullScore": false,
        "knockout": false,
        "includeInEvaluation": true,
        "createdById": "user-uuid",
        "createdAt": "2024-01-01T00:00:00Z",
        "updatedAt": "2024-01-01T00:00:00Z",
        "archivedAt": null
      },
      {
        "id": "survey-question-uuid-2",
        "title": "Tell us about yourself",
        "type": "FREE_TEXT",
        "organizationId": "org-uuid",
        "teamId": "team-uuid",
        "supportingVideoURL": null,
        "maxCharacterLength": 1000,
        "includeScoring": false,
        "selectAllForFullScore": false,
        "knockout": false,
        "includeInEvaluation": false,
        "createdById": "user-uuid",
        "createdAt": "2024-01-01T00:00:00Z",
        "updatedAt": "2024-01-01T00:00:00Z",
        "archivedAt": null
      }
    ],
    "pagination": {
      "total": 2,
      "page": 0,
      "pages": 1,
      "pageSize": 50
    }
  },
  "meta": {
    "requestId": "uuid",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

Get Survey Question

Retrieve a specific survey question by ID. Endpoint: GET /qsi/gather/survey-questions/{surveyQuestionId}

surveyQuestionId

string

required

UUID of the survey question to retrieve

teamId

string

Optional override for team ID. If not provided, will be resolved from your API credential (teamId or defaultTeamId). Required if using an organization-level API key without a defaultTeamId.

{
  "data": {
    "surveyQuestion": {
      "id": "survey-question-uuid",
      "type": "MULTIPLE_CHOICE",
      "title": "What is your preferred work style?",
      "includeScoring": true,
      "knockout": false,
      "selectAllForFullScore": false,
      "maxCharacterLength": null,
      "supportingVideoURL": null,
      "organizationId": "org-uuid",
      "teamId": "team-uuid",
      "createdById": "user-uuid",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z",
      "archivedAt": null
    }
  },
  "meta": {
    "requestId": "uuid",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

Update Survey Question

Update survey question properties. Only include fields you want to update. Endpoint: PATCH /qsi/gather/survey-questions/{surveyQuestionId}

surveyQuestionId

string

required

UUID of the survey question to update

{
  "title": "Updated survey question title",
  "options": [
    {
      "id": "existing-option-uuid",
      "title": "Updated Option 1",
      "weight": 5,
      "ordinal": 1
    },
    {
      "title": "New Option",
      "weight": 3,
      "ordinal": 2
    }
  ],
  "removedOptionIds": ["old-option-uuid"]
}

Archive Survey Question

Archive a survey question (soft delete). Endpoint: DELETE /qsi/gather/survey-questions/{surveyQuestionId}

surveyQuestionId

string

required

UUID of the survey question to archive

userId

string

User ID for the archive action. If not provided, will be resolved from API credential.

{
  "data": {
    "surveyQuestion": {
      "id": "survey-question-uuid",
      "archivedAt": "2024-01-01T00:00:00Z"
    }
  },
  "meta": {
    "requestId": "uuid",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

AI Text Questions

AI text questions are used in AI-powered interviews where candidates provide written responses that are evaluated by AI.

Create AI Text Question

Create a new AI text question. Endpoint: POST /qsi/gather/ai-text-questions

cURL
JavaScript
Python

curl -X POST https://api.prod.qualifi.hr/qsi/gather/ai-text-questions \
  -H "x-api-key: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Technical Assessment",
    "description": "A comprehensive technical question for candidates",
    "questionText": "Explain the difference between REST and GraphQL APIs, including their use cases and trade-offs."
  }'

const response = await fetch('https://api.prod.qualifi.hr/qsi/gather/ai-text-questions', {
  method: 'POST',
  headers: {
    'x-api-key': apiKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Technical Assessment',
    description: 'A comprehensive technical question for candidates',
    questionText: 'Explain the difference between REST and GraphQL APIs, including their use cases and trade-offs.'
  })
});
const question = await response.json();

response = requests.post(
    'https://api.prod.qualifi.hr/qsi/gather/ai-text-questions',
    headers={
        'x-api-key': api_key,
        'Content-Type': 'application/json'
    },
    json={
        'title': 'Technical Assessment',
        'description': 'A comprehensive technical question for candidates',
        'questionText': 'Explain the difference between REST and GraphQL APIs, including their use cases and trade-offs.'
    }
)
question = response.json()

{
  "title": "Technical Assessment",
  "description": "A comprehensive technical question for candidates",
  "questionText": "Explain the difference between REST and GraphQL APIs, including their use cases and trade-offs."
}

List AI Text Questions

List AI text questions with pagination and filtering. Endpoint: GET /qsi/gather/ai-text-questions

page

number

Page number (0-indexed, default: 0)

pageSize

number

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

string

Search term to filter by title

archived

boolean

Filter by archived status (true, false, or omit for all)

teamId

string

Optional override for team ID. If not provided, will be resolved from your API credential (teamId or defaultTeamId). Required if using an organization-level API key without a defaultTeamId.

cURL
JavaScript
Python

curl -X GET "https://api.prod.qualifi.hr/qsi/gather/ai-text-questions?page=0&pageSize=50" \
  -H "x-api-key: ${API_KEY}"

const params = new URLSearchParams({
  page: '0',
  pageSize: '50'
});

const response = await fetch(
  `https://api.prod.qualifi.hr/qsi/gather/ai-text-questions?${params}`,
  {
    headers: {
      'x-api-key': apiKey
    }
  }
);
const data = await response.json();

params = {
    'page': 0,
    'pageSize': 50
}
response = requests.get(
    'https://api.prod.qualifi.hr/qsi/gather/ai-text-questions',
    headers={'x-api-key': api_key},
    params=params
)
data = response.json()

{
  "data": {
    "aiTextQuestions": [
      {
        "id": "ai-text-question-uuid",
        "title": "Technical Assessment",
        "description": "A comprehensive technical question for candidates",
        "questionText": "Explain the difference between REST and GraphQL APIs.",
        "organizationId": "org-uuid",
        "teamId": "team-uuid",
        "createdById": "user-uuid",
        "createdAt": "2024-01-01T00:00:00Z",
        "updatedAt": "2024-01-01T00:00:00Z",
        "archivedAt": null
      }
    ],
    "pagination": {
      "total": 10,
      "page": 0,
      "pages": 1,
      "pageSize": 50
    }
  },
  "meta": {
    "requestId": "uuid",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

Get AI Text Question

Retrieve a specific AI text question by ID. Endpoint: GET /qsi/gather/ai-text-questions/{aiTextQuestionId}

aiTextQuestionId

string

required

UUID of the AI text question to retrieve

teamId

string

Optional override for team ID. If not provided, will be resolved from your API credential (teamId or defaultTeamId). Required if using an organization-level API key without a defaultTeamId.

{
  "data": {
    "aiTextQuestion": {
      "id": "ai-text-question-uuid",
      "title": "Technical Assessment",
      "description": "A comprehensive technical question for candidates",
      "questionText": "Explain the difference between REST and GraphQL APIs, including their use cases and trade-offs.",
      "organizationId": "org-uuid",
      "teamId": "team-uuid",
      "createdById": "user-uuid",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z",
      "archivedAt": null
    }
  },
  "meta": {
    "requestId": "uuid",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

Update AI Text Question

Update AI text question properties. Only include fields you want to update. Endpoint: PATCH /qsi/gather/ai-text-questions/{aiTextQuestionId}

aiTextQuestionId

string

required

UUID of the AI text question to update

{
  "title": "Updated Technical Assessment",
  "description": "Updated description",
  "questionText": "Updated question text with more details."
}

Archive AI Text Question

Archive an AI text question (soft delete). Endpoint: DELETE /qsi/gather/ai-text-questions/{aiTextQuestionId}

aiTextQuestionId

string

required

UUID of the AI text question to archive

userId

string

User ID for the archive action. If not provided, will be resolved from API credential.

{
  "data": {
    "aiTextQuestion": {
      "id": "ai-text-question-uuid",
      "archivedAt": "2024-01-01T00:00:00Z"
    }
  },
  "meta": {
    "requestId": "uuid",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

Unarchive AI Text Question

Unarchive a previously archived AI text question. Endpoint: POST /qsi/gather/ai-text-questions/{aiTextQuestionId}/unarchive

aiTextQuestionId

string

required

UUID of the AI text question to unarchive

{}

Get Questions by Interview

Retrieve all questions (audio questions, survey questions, and AI text questions) associated with a specific interview, sorted by ordinal. Endpoint: GET /qsi/gather/questions/interview/{interviewId}

interviewId

string

required

UUID of the interview

teamId

string

Optional override for team ID. If not provided, will be resolved from your API credential (teamId or defaultTeamId). Required if using an organization-level API key without a defaultTeamId.

cURL
JavaScript
Python

curl -X GET https://api.prod.qualifi.hr/qsi/gather/questions/interview/{interviewId} \
  -H "x-api-key: ${API_KEY}"

const response = await fetch(
  `https://api.prod.qualifi.hr/qsi/gather/questions/interview/${interviewId}`,
  {
    headers: {
      'x-api-key': apiKey
    }
  }
);
const data = await response.json();

response = requests.get(
    f'https://api.prod.qualifi.hr/qsi/gather/questions/interview/{interview_id}',
    headers={'x-api-key': api_key}
)
data = response.json()

{
  "data": {
    "questions": [
      {
        "id": "uuid",
        "title": "Question title",
        "audioURL": "https://...",
        "audioType": "question",
        "ordinal": 1,
        "transcription": "...",
        "organizationId": "uuid",
        "teamId": "uuid",
        "createdAt": "2024-01-01T00:00:00Z",
        "updatedAt": "2024-01-01T00:00:00Z"
      }
    ]
  },
  "meta": {
    "requestId": "uuid",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

Returns all question types (audio questions, survey questions, and AI text questions) associated with the interview. Questions are sorted by ordinal. Audio URLs are automatically converted to MP3 format. Survey questions and AI text questions will have audioType: null and audioURL: null.

Audio Generation

Audio questions support text-to-speech (TTS) audio generation:

TTS Providers: WellSaid or current TTS model
Async Processing: Audio generation happens asynchronously
Webhook Notifications: Use webhooks to be notified when audio generation completes
Pre-uploaded Audio: Alternatively, provide your own audioURL

When questionScript is provided with narratorId, the question is created immediately, but audioURL may be null until generation completes. Check the transcriptionStatus field to monitor generation progress.

Interviews

Learn how to use questions in interviews

Narrators

Explore available narrators for TTS

Get Started

API Reference

Guides

Code Examples

Resources

Overview

Audio Questions

Create Audio Question

List Audio Questions

Get Audio Question

Update Audio Question

Archive Audio Question

Survey Questions

Survey Question Types

Create Survey Question

List Survey Questions

Get Survey Question

Update Survey Question

Archive Survey Question

AI Text Questions

Create AI Text Question

List AI Text Questions

Get AI Text Question

Update AI Text Question

Archive AI Text Question

Unarchive AI Text Question

Get Questions by Interview

Audio Generation

Interviews

Narrators

Get Started

API Reference

Guides

Code Examples

Resources

Documentation Index

​Overview

​Audio Questions

​Create Audio Question

​List Audio Questions

​Get Audio Question

​Update Audio Question

​Archive Audio Question

​Survey Questions

​Survey Question Types

​Create Survey Question

​List Survey Questions

​Get Survey Question

​Update Survey Question

​Archive Survey Question

​AI Text Questions

​Create AI Text Question

​List AI Text Questions

​Get AI Text Question

​Update AI Text Question

​Archive AI Text Question

​Unarchive AI Text Question

​Get Questions by Interview

​Audio Generation

​Related Resources

Interviews

Narrators

Overview

Audio Questions

Create Audio Question

List Audio Questions

Get Audio Question

Update Audio Question

Archive Audio Question

Survey Questions

Survey Question Types

Create Survey Question

List Survey Questions

Get Survey Question

Update Survey Question

Archive Survey Question

AI Text Questions

Create AI Text Question

List AI Text Questions

Get AI Text Question

Update AI Text Question

Archive AI Text Question

Unarchive AI Text Question

Get Questions by Interview

Audio Generation

Related Resources