> ## 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.

# Creating Your First Interview

> Step-by-step guide to creating your first interview with questions

## Overview

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

<Steps>
  <Step title="Create your first question">
    Start by creating a question with text-to-speech audio generation:

    <Tabs>
      <Tab title="cURL">
        ```bash theme={null}
        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"
          }'
        ```
      </Tab>

      <Tab title="JavaScript">
        ```javascript theme={null}
        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);
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={null}
        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'])
        ```
      </Tab>
    </Tabs>

    <Callout type="info">
      Save the question ID from the response. You'll need it when creating the interview.
    </Callout>
  </Step>

  <Step title="Create additional questions">
    Create a few more questions for your interview:

    ```json theme={null}
    {
      "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"
    }
    ```

    ```json theme={null}
    {
      "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.
  </Step>

  <Step title="Create the interview">
    Create an interview with your questions:

    <Tabs>
      <Tab title="cURL">
        ```bash theme={null}
        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"]
          }'
        ```
      </Tab>

      <Tab title="JavaScript">
        ```javascript theme={null}
        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);
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={null}
        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'])
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Create a candidate">
    Create a candidate to invite:

    <Tabs>
      <Tab title="cURL">
        ```bash theme={null}
        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": "john.doe@example.com",
            "phone": "+1234567890"
          }'
        ```
      </Tab>

      <Tab title="JavaScript">
        ```javascript theme={null}
        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: 'john.doe@example.com',
            phone: '+1234567890'
          })
        });

        const candidate = await response.json();
        console.log('Candidate ID:', candidate.data.id);
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={null}
        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': 'john.doe@example.com',
                'phone': '+1234567890'
            }
        )

        candidate = response.json()
        print('Candidate ID:', candidate['data']['id'])
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Send the interview invite">
    Create a candidate interview and send the invite:

    <Tabs>
      <Tab title="cURL">
        ```bash theme={null}
        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"]
          }'
        ```
      </Tab>

      <Tab title="JavaScript">
        ```javascript theme={null}
        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);
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={null}
        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'])
        ```
      </Tab>
    </Tabs>

    <Callout type="success">
      The candidate will receive an email invite with a link to start the interview!
    </Callout>
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Sending Invites" icon="mail" href="/guides/sending-invites">
    Learn more about sending invites via email and SMS
  </Card>

  <Card title="Handling Webhooks" icon="webhook" href="/guides/handling-webhooks">
    Set up webhooks to be notified when interviews are completed
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/interviews">
    Explore all available endpoints
  </Card>

  <Card title="Best Practices" icon="check-circle" href="/guides/best-practices">
    Review best practices for API usage
  </Card>
</CardGroup>

## Common Issues

<AccordionGroup>
  <Accordion title="Audio not generated">
    Audio generation is asynchronous. Check the question's `transcriptionStatus`
    field or set up a webhook for `question.audio_generated` events.
  </Accordion>

  <Accordion title="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"`.
  </Accordion>

  <Accordion title="Invalid phone number">
    Phone numbers must be in E.164 format (e.g., `+1234567890`). Include country
    code.
  </Accordion>
</AccordionGroup>