Creating Your First Interview

Overview

This guide walks you through creating your first interview using the Gather API, from creating questions to sending invites to candidates.

Create your first question

Start by creating a question with text-to-speech audio generation:

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",
    "questionScript": "Tell me about yourself and your background.",
    "audioURL": "https://example.com/audio/question1.mp3"
  }'

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',
    questionScript: 'Tell me about yourself and your background.',
    audioURL: 'https://example.com/audio/question1.mp3'
  })
});

const question = await response.json();
console.log('Question ID:', question.data.id);

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',
        'questionScript': 'Tell me about yourself and your background.',
        'audioURL': 'https://example.com/audio/question1.mp3'
    }
)

question = response.json()
print('Question ID:', question['data']['id'])

Save the question ID from the response. You’ll need it when creating the interview.

Create additional questions

Create a few more questions for your interview:

{
  "userId": "user-uuid",
  "title": "Why are you interested in this role?",
  "questionScript": "Why are you interested in this position?",
  "audioURL": "https://example.com/audio/question2.mp3"
}

{
  "userId": "user-uuid",
  "title": "What are your strengths?",
  "questionScript": "What do you consider to be your greatest strengths?",
  "audioURL": "https://example.com/audio/question3.mp3"
}

Keep track of all question IDs.

Create the interview

Create an interview with your questions:

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": ["question-id-1", "question-id-2", "question-id-3"]
  }'

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: ['question-id-1', 'question-id-2', 'question-id-3']
  })
});

const interview = await response.json();
console.log('Interview ID:', interview.data.id);

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': ['question-id-1', 'question-id-2', 'question-id-3']
    }
)

interview = response.json()
print('Interview ID:', interview['data']['id'])

Create a candidate

Create a candidate to invite:

cURL
JavaScript
Python

curl -X POST https://api.prod.qualifi.hr/qsi/gather/candidates \
  -H "x-api-key: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "phone": "+1234567890"
  }'

const response = await fetch('https://api.prod.qualifi.hr/qsi/gather/candidates', {
  method: 'POST',
  headers: {
    'x-api-key': apiKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    firstName: 'John',
    lastName: 'Doe',
    email: '[email protected]',
    phone: '+1234567890'
  })
});

const candidate = await response.json();
console.log('Candidate ID:', candidate.data.id);

response = requests.post(
    'https://api.prod.qualifi.hr/qsi/gather/candidates',
    headers={
        'x-api-key': api_key,
        'Content-Type': 'application/json'
    },
    json={
        'firstName': 'John',
        'lastName': 'Doe',
        'email': '[email protected]',
        'phone': '+1234567890'
    }
)

candidate = response.json()
print('Candidate ID:', candidate['data']['id'])

Send the interview invite

Create a candidate interview and send the invite:

cURL
JavaScript
Python

curl -X POST https://api.prod.qualifi.hr/qsi/gather/candidate-interviews \
  -H "x-api-key: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "candidateId": "candidate-id",
    "interviewId": "interview-id",
    "sendInvite": true,
    "deliveryTypes": ["email"]
  }'

const response = await fetch('https://api.prod.qualifi.hr/qsi/gather/candidate-interviews', {
  method: 'POST',
  headers: {
    'x-api-key': apiKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    candidateId: 'candidate-id',
    interviewId: 'interview-id',
    sendInvite: true,
    deliveryTypes: ['email']
  })
});

const candidateInterview = await response.json();
console.log('Invite sent!', candidateInterview.data);

response = requests.post(
    'https://api.prod.qualifi.hr/qsi/gather/candidate-interviews',
    headers={
        'x-api-key': api_key,
        'Content-Type': 'application/json'
    },
    json={
        'candidateId': 'candidate-id',
        'interviewId': 'interview-id',
        'sendInvite': True,
        'deliveryTypes': ['email']
    }
)

candidate_interview = response.json()
print('Invite sent!', candidate_interview['data'])

The candidate will receive an email invite with a link to start the interview!

Next Steps

Sending Invites

Learn more about sending invites via email and SMS

Handling Webhooks

Set up webhooks to be notified when interviews are completed

API Reference

Explore all available endpoints

Best Practices

Review best practices for API usage

Common Issues

Audio not generated

Audio generation is asynchronous. Check the question’s transcriptionStatus field or set up a webhook for question.audio_generated events.

Invite not received

Verify the candidate’s email address is correct and check spam folders. Ensure sendInvite is set to true and deliveryTypes includes "email".

Invalid phone number

Phone numbers must be in E.164 format (e.g., +1234567890). Include country code.

Get Started

API Reference

Guides

Code Examples

Resources

Creating Your First Interview

Overview

Next Steps

Sending Invites

Handling Webhooks

API Reference

Best Practices

Common Issues

Get Started

API Reference

Guides

Code Examples

Resources

​Overview

​Next Steps

Sending Invites

Handling Webhooks

API Reference

Best Practices

​Common Issues

Overview

Next Steps

Common Issues