Candidate Interviews API
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.