🎤 Conducting an interview

This is a quick guide to conducting a general interview using Ribbon API.

Let's create our first Interview - we're going to create a simple survey for McDonald's. We want to ask three questions:

When and where was the last time you visited McDonald's?
What's your favorite item on the McDonald's menu?
If you could introduce one new item to the menu, what would you introduce?

Step 1: Create an Interview Flow

First, create an Interview Flow with these questions, by making a POST request to /interview-flows

curl --request POST \
     --url https://app.ribbon.ai/be-api/v1/interview-flows \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <your-api-key-here>' \
     --header 'content-type: application/json' \
     --data @- <<EOF
{
  "org_name": "McDonald's",
  "title": "Survey",
  "questions": [
    "When and where was the last time you visited McDonald's?",
    "What's your favorite item on the McDonald's menu?",
    "If you could introduce one new item to the menu, what would you introduce?"
  ]
}
EOF

const url = 'https://app.ribbon.ai/be-api/v1/interview-flows';
const options = {
  method: 'POST',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    authorization: 'Bearer <your-api-key-here>'
  },
  body: JSON.stringify({
    org_name: 'McDonald\'s',
    title: 'Survey',
    questions: [
      'When and where was the last time you visited McDonald\'s?',
      'What\'s your favorite item on the McDonald\'s menu?',
      'If you could introduce one new item to the menu, what would you introduce?'
    ]
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

{
	"interview_flow_id":"12f4493d"
}

This will return an interview_flow_id - you can use this ID to create single-use interview links.

Step 2: Create an Interview and Interview Link

Next, we create an Interview and single-use interview link by making a POST request to /interviews using our interview_flow_id

curl --request POST \
     --url https://app.ribbon.ai/be-api/v1/interviews \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <your-api-key-here>' \
     --header 'content-type: application/json' \
     --data '
{
  "interview_flow_id": "<your-interview-flow-id>"
}
'

const url = 'https://staging.ribbon.ai/be-api/v1/interviews';
const options = {
  method: 'POST',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    authorization: 'Bearer <your-api-key-here>'
  },
  body: JSON.stringify({interview_flow_id: '12f4493d'})
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));


{
  "interview_id":"3346dfe0-0093-4fb8-9249-31d0c86d0210",
  "interview_link":"https://app.ribbon.ai/interview/api/12f4493d/3346dfe0-0093-4fb8-9249-31d0c86d0210"
}

Visiting the interview_link above takes us here:

That's it! Anyone who visits this link can complete your interview with our intelligent voice agent. Congratulations, you've created your first AI-powered interview.

🔍 Retrieving interviews

You can retrieve a list of completed and incomplete interviews by making a GET request to /interviews

curl --request GET \
     --url https://app.ribbon.ai/be-api/v1/interviews \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <your-api-key-here>'

const url = 'https://app.ribbon.ai/be-api/v1/interviews';
const options = {
  method: 'GET',
  headers: {accept: 'application/json', authorization: 'Bearer <your-api-key-here>'}
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

{
  "interviews": [
    {
      "interview_data": {
        "transcript": "<full transcript of the interview>",
        "transcript_with_timestamp": [
          {
            "content": "Hello! How are you doing today?",
            "role": "agent",
            "words": [
              {
                "end": 0.736684326171875,
                "start": 0.125105224609375,
                "word": "Hello!"
              }
              // ... word level timestamps
            ]
          }
        ],
        "interview_flow_id": "490c8ddf",
        "interview_id": "dabdf2a3-a680-41cf-a7e0-f2175e77c971",
        "status": "completed"
      }
    }
    /// ... more interviews
  ]
}