Candidate Interviews API

Edited

Note: the following documentation is outdated — please see our new Developer Portal API Reference documentation instead.

Getting Started

1. Create an API Key

An API key is required to use the Alpharun API. To create an API key, go to Developer Settings, and then click "Create API Key". Store the key you created in a safe place like a password manager.

2. Get your Project ID

Open the Project you want to access through the API, click the three dot menu on the top right corner, and select "Copy Project ID"

Interview Object

Interviews retrieved through the API will have the following format:

Property

Type

Description

id

string

Unique identifier for the interview

project_id

string

Identifier of the project this interview belongs to

status

string

Current status of the interview: "in_progress" (interviewee has not answered all questions) or "completed"

contact

object

Information about the interviewee

contact.first_name

string | null

First name of the interviewee

contact.last_name

string | null

Last name of the interviewee

contact.email

string | null

Email address of the interviewee

contact.phone_number

string | null

Phone number of the interviewee

started_at

string

ISO 8601 timestamp of when the interview started

completed_at

string

ISO 8601 timestamp of when the interview was completed

transcript_fragments

array

List of transcript fragments in chronological order

transcript_fragments[].role

string

Role of the speaker ("agent" or "participant")

transcript_fragments[].transcript

string

The spoken content

insights

object

AI-generated insights for this interview. Note that insights are only generated for completed interviews, so these values may be null for partially completed interviews.

insights.summary

string | null

A short 3-6 sentence summary of the interview.

insights.assessment_score

number | null

An overall rating (1 to 5) of how qualified the candidate is for this role, based on the assessment criteria.

assessment_criteria[]

array

List of assessments (e.g. evaluation criteria)

assessment_criteria[].name

string

The criteria to assess (e.g. "At least 2 years of customer support experience")

assessment_criteria[].value

boolean | string

The candidate's value for the criteria

assessment_criteria[].commentary

string

Evaluation comments for the relevant criteria (e.g. "4 years of customer support experience dealing with B2B clients.")

API Endpoints

List Interviews within a Project

The list interviews endpoint allows you to retrieve interview transcripts for a specific project.

Endpoint

GET https://api.alpharun.com/api/v1/projects/{PROJECT_ID}/interviews

Query Parameters

 - page (optional) - number

The page size is 20 interviews and interviews are sorted from most recent to oldest. You can use the page query parameter to retrieve additional interviews.

Example response

Returns an array of Interview objects, along with pagination details.

{
  "interviews": [
    {
      "id": "abc123",
      "project_id": "def456",
      "status": "completed",
      "contact": {
        "first_name": "Miguel",
        "last_name": "Rodriguez",
        "email": "miguel.rodriguez@alpharun.com",
        "phone_number": null
      },
      "started_at": "2024-05-29T22:43:16.029+00:00",
      "completed_at": "2024-05-29T22:43:16.029+00:00",
      "transcript_fragments": [
        {
          "role": "agent",
          "transcript": "Hello, is this Miguel Rodriguez?"
        },
        {
          "role": "participant",
          "transcript": "Yes, this is Miguel. How are you?"
        },
        {
          "role": "agent",
          "transcript": "I'm doing well, thank you. Let's get started with the interview. Can you describe any previous experience in customer support that you have?"
        },
        {
          "role": "participant",
          "transcript": "Certainly. I've been working in customer support for over two years now. My first role was at a call center where I handled inquiries and complaints from customers. Recently, I worked with an e-commerce company where I provided support via chat and email."
        },
        {
          "role": "agent",
          "transcript": "That's great to hear. What motivated you to apply for this position at Acme, and what interests you about working in a BPO environment?"
        },
        {
          "role": "participant",
          "transcript": "I have always been drawn to roles that require strong interpersonal skills and problem-solving abilities. What's appealing about Acme is its reputation for excellent team collaboration and its dedication to client satisfaction. The BPO environment facilitates constant learning and growth, which is very exciting for me."
        },
        {
          "role": "agent",
          "transcript": "How would you rate your English proficiency, and in what ways have you used English in your previous customer support roles?"
        },
        {
          "role": "participant",
          "transcript": "I would rate my English proficiency at a C1 level. In my previous roles, I communicated with clients exclusively in English, both verbally and in writing, including providing detailed explanations and resolving issues effectively."
        },
        {
          "role": "agent",
          "transcript": "Can you provide an example of a time when you collaborated with a team to resolve a customer issue?"
        },
        {
          "role": "participant",
          "transcript": "Certainly. At my last job, we had a situation where a customer's package was lost. I coordinated with the logistics team to track the item, liaised with the warehouse to confirm inventory, and worked with my supervisor to arrange a replacement. Throughout this process, clear and constant communication was key."
        },
        {
          "role": "agent",
          "transcript": "How do you handle high-pressure situations or difficult customers when providing support?"
        },
        {
          "role": "participant",
          "transcript": "I stay calm and listen actively. It's important to let the customer express their frustration while I calmly gather necessary information. I then assure them that I'm here to help and quickly come up with a solution. Staying patient and empathetic is crucial."
        },
        {
          "role": "agent",
          "transcript": "What strategies do you use to ensure effective communication and support for clients?"
        },
        {
          "role": "participant",
          "transcript": "Clear and simple language is essential. I make sure to be concise but thorough, and I always confirm understanding by asking follow-up questions. Regular updates and follow-through are also important to keep the client informed."
        },
        {
          "role": "agent",
          "transcript": "Why do you believe it is important to provide excellent customer service, especially in the context of supporting American clients?"
        },
        {
          "role": "participant",
          "transcript": "Providing excellent customer service builds trust and loyalty, which are key to any business. American clients, in particular, appreciate responsive and friendly interaction. It’s important to meet their expectations to foster repeat business and positive word-of-mouth."
        },
        {
          "role": "agent",
          "transcript": "How do you stay motivated and maintain a positive attitude while handling repetitive or challenging tasks in customer support?"
        },
        {
          "role": "participant",
          "transcript": "I remind myself of the impact my work has on people’s lives. Small gestures, like resolving an issue or making someone's day better, are very rewarding. I also take brief breaks to recharge and keep a positive mindset."
        },
        {
          "role": "agent",
          "transcript": "Can you describe a significant achievement in your customer support career that you are particularly proud of?"
        },
        {
          "role": "participant",
          "transcript": "Sure. One time, I was able to turn around a difficult situation with a very upset customer by going above and beyond to resolve their issue. This led to the customer later submitting a commendation for my assistance, which was a very proud moment for me."
        },
        {
          "role": "agent",
          "transcript": "What software or tools are you familiar with that can aid in providing exceptional customer service?"
        },
        {
          "role": "participant",
          "transcript": "I am well-versed in using CRM software like Salesforce and Zendesk. I also have experience with live chat tools, email management systems, and basic Excel functions for reporting purposes."
        },
        {
          "role": "agent",
          "transcript": "Thank you, Miguel. We will be in touch soon regarding the next steps."
        },
        {
          "role": "participant",
          "transcript": "Thank you for the opportunity. I look forward to hearing from you."
        }
      ],
      "insights": {
        "assessment_score": 5
        "summary": "Miguel Rodriguez demonstrated strong customer support experience and a high level of English proficiency. His responses reflected exceptional problem-solving skills, teamwork, and a customer-first mindset. Overall, he presented himself as a highly qualified candidate for the Customer Service Representative role at Acme.",
        "assessments": [
          {
            "criteria": "Has at least a CEFR B2 English language level?",
            "rating": true,
            "comment": "Candidate answered questions with comprehension, vocabulary, and grammar associated with a C1 level."
          },
          {
            "criteria": "Has 1+ years of customer support experience?",
            "rating": true,
            "comment": "Candidate has three years of support experience."
          },
          {
            "criteria": "Is comfortable with decision-making and problem-solving?",
            "rating": true,
            "comment": "Candidate describes a strategic approach to overcoming support challenges."
          },
          {
            "criteria": "Has a positive, customer-friendly attitude?",
            "rating": true,
            "comment": "Candidate mentioned the fulfillment they get from positively impacting a customer's day."
          },
          {
            "criteria": "Has support software experience?",
            "rating": true,
            "comment": "Candidate is well versed with Salesforce and Zendesk."
          },
        ]
      }
    }
  ],
  "total_pages": 1,
  "total": 1,
  "page": 1,
  "limit": 20
}

Get the audio recording from an interview call

This endpoint returns the audio recording of a call within a given interview. To get a call ID, use the list Interview endpoint and then use the interview.calls[].id property.

Endpoint

GET https://api.alpharun.com/api/v1/projects/{PROJECT_ID}/interviews/{INTERVIEW_ID}/calls/{CALL_ID}/recording

Response

Returns the full .wav audio recording.