🧠 What is Ribbon API?

Ribbon API lets you create intelligent AI-powered voice interviews. To interview someone, all you have to do is share a link.

Ribbon's AI interviewer can hold a natural and intelligent conversation with your interviewee. You can use the Ribbon API to create many types of interviews including: product interviews, surveys, recruitment interviews, health questionnaires, and much more. Use your imagination!

📖 Concepts

Ribbon API has two concepts: Interview Flows and Interviews

Interview Flows are reusable sets of questions and context.

Interviews are created from Interviews Flows. Each interview has a one use session link. To interview someone, all you have to do is share the link! Once the interviewee has visited the interview link, the link is expired.

🔒 Authentication

Create your first API key on the Ribbon API console page.

When making an API call, add an Authorization header and set the API key as a Bearer Token:

Bearer <your-api-key-here>

You can test your API key by making a call to /ping

🎤 Quick start to conducting interviews

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