Questions

Overview

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

Create Question

Create a new 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 '{
    "userId": "user-uuid",
    "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({
      userId: 'user-uuid',
      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={
        'userId': 'user-uuid',
        '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()

{
  "userId": "user-uuid",
  "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 required and identifies the user who will be marked as the creator of the question. This user must belong to the organization and team associated with your API key.

Get Question

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

questionId

string

required

UUID of the question to retrieve

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

List Survey Questions

List survey questions (multiple choice, free text, yes/no questions) for a team/organization. Use this endpoint to get survey question IDs that you can use when creating interviews. Endpoint: GET /qsi/gather/survey-questions

page

number

Page number (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)

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

Survey questions are different from audio questions. Use this endpoint to get survey question IDs for questionnaire-type interviews or to add survey questions to standard interviews.

Get Questions by Interview

Retrieve all questions (audio questions and survey 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 from API credential

{
  "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 both audio questions and survey questions. Questions are sorted by ordinal. Audio URLs are automatically converted to MP3 format. Survey questions will have audioType: null and audioURL: null.

List Questions

List all 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

Include archived questions (default: false)

string

Search term to filter by title/description

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

Update Question

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

Delete Question

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

questionId

string

required

UUID of the question to archive

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

Audio Generation

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 generateAudio is true, 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

Create Question

Get Question

List Survey Questions

Get Questions by Interview

List Questions

Update Question

Delete Question

Audio Generation

Interviews

Narrators

Get Started

API Reference

Guides

Code Examples

Resources

​Overview

​Create Question

​Get Question

​List Survey Questions

​Get Questions by Interview

​List Questions

​Update Question

​Delete Question

​Audio Generation

​Related Resources

Interviews

Narrators

Overview

Create Question

Get Question

List Survey Questions

Get Questions by Interview

List Questions

Update Question

Delete Question

Audio Generation

Related Resources