Gallery
Share
Explore

Duolingo interviewer recommendations API

Overview

Duolingo are to provide an API as outlined in the schema below. A brief summary of this is that Guide will make a request containing interview requirements (essentially an id and a set of interviewer requirements) and will get back a set of interview recommendations which will map from the given ids of the interview and interviewer requirements to an email address for the interviewer that fulfils that requirement.

Security

An API key is to provided in the request header api_key which will then be validated by Duolingo. Should the API key be incorrect a response of 401 should be returned.

Schema

Below is the proposed schema in OpenAPI format. You can more easily view this schema by pasting into
https://editor.swagger.io/
⁠
⁠
openapi: 3.0.3
info:
title: Duolingo/Guide Interviewer Recommendations - OpenAPI 3.0
description: |-
This is a proposal for the communication between Duolingo and Guide providing an endpoint for Guide to query and recieve back interviewers to use for a given interview panel. This API would be built by and maintained by Duolingo.
Security is to be provided by a simple API key that will be provided by Duolingo to Guide and checked on request.
version: 1.0.0
paths:
/interviews/interviewer-recommendations:
post:
description: |-
The main endpoint of this API that will be called to get interviewer recommendations for an interview. Note: we are agnostic as to the name of this endpoint, the current name can be treated as a placeholder.
Takes in a set of InterviewRequirements that make up the panel, and will get back a list of InterviewRecommendations.
operationId: getInterviewerRecommendations
security:
- api_key: []
requestBody:
content:
application/json:
schema:
type: object
properties:
interviewRequirements:
type: array
items:
$ref: '#/components/schemas/InterviewRequirement'
responses:
'200':
description: Default response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
description: Whether the operation was successful or not.
error:
type: string
description: Optional. If success is false will include an error message.
interviewRecommendations:
$ref: '#/components/schemas/InterviewRecommendation'
'401':
description: Invalid API Key
components:
schemas:
InterviewRequirement:
type: object
properties:
id:
type: string
format: uuid
description: A unique identifier generated by Guide for this requirement.
startTime:
type: string
format: date-time
description: The proposed start time of this interview, in ISO format.
example: 2024-04-03T10:00:00.000Z
duration:
type: integer
format: int64
description: The length of the interview in minutes.
example: 30
interviewId:
type: string
format: uuid
description: A unique identifier generated by Guide for this interview.
interviewName:
type: string
description: The user friendly string that defines the interview. Given that the interview ids will not have meaning in the Duolingo system it is proposed that this will be used as the identifier.
interviewerRequirements:
type: array
description: A list of interviewer requirements for this interview.
items:
$ref: '#/components/schemas/InterviewerRequirement'
InterviewerRequirement:
type: object
properties:
id:
type: string
format: uuid
description: A unique identifier generated by Guide for this interviewer requirement.
interviewerOptionEmails:
type: array
example: []
description: The email addresses of the interviewers required for this requirement. One of these should be used as the interviewer. This is optional; either this or the interviewerPoolId will be provided.
items:
type: string
format: email
interviewerPoolId:
type: string
format: uuid
description: The unique identifier for the interviewer pool that is to be used. This is optional; either this or the interviewerOptionEmails is provided. These are generated by Guide and provided via a separate API so that Duolingo has knowledge of these ids, and the users in the pools etc.
includeTrainee:
type: boolean
description: Whether a trainee should be included as part of this requirement. Will only be provided if an interviewerPoolId is provided. If true, then this requirement requires both a lead interviewer and a trainee to be chosen from the pool. If false, only a lead interviewer should be provided.
InterviewRecommendation:
type: object
properties:
interviewRequirementId:
type: string
format: uuid
description: The unique identifier that was provided by Guide for the interview requirement. This represents the interview requirement these interviewers are for.
interviewers:
type: array
description: The list of fulfill interviewer requirements for this interview.
items:
$ref: '#/components/schemas/InterviewerRecommendation'
InterviewerRecommendation:
type: object
properties:
interviewerRequirementId:
type: string
format: uuid
description: The unique identifier that was provided by Guide for the interviewer requirement. This represents the interviewer requirement this is fulfilling.
interviewerEmails:
type: array
description: 'A list of interviewers that should be used to fulfil this requirement. Note: although this is an array we would currently expect the length to always be 1.'
items:
type: string
format: email
traineeEmails:
type: array
description: 'A list of trainee that should be used to fulfil this requirement. Note: although this is an array we would currently expect the length to always be 1.'
items:
type: string
format: email

securitySchemes:
api_key:
type: apiKey
name: api_key
in: header

Example

We have 2 interviews; “Tech screen” and “System design”. For Tech screen the interviewers should be will@example.com, and 1 user from the engineering pool (id: 9988cfdf-a772-4741-ba0a-b11aa4221d9c). The system design interview requires 1 user from the engineering pool and a trainee.
The request body to the API would be as follows:
{
"interviewRequirements": [
{
"id": "e63c444c-4802-47c1-9e02-cf37abc77ac4",
"startTime": "2024-04-03T10:00:00.000Z",
"duration": 60,
"interviewId": "8336fdda-d125-4566-ad1a-77e00c6943a7",
"interviewName": "Tech screen",
"interviewerRequirements": [
{
"id": "9ad4f37c-5407-4dec-b4fb-93b8f5061c1c",
"interviewerOptionEmails": [
"will@example.com"
]
},
{
"id": "2e62ff08-7ff8-40a5-85d9-f1ddc404f0ee",
"interviewerPoolId": "9988cfdf-a772-4741-ba0a-b11aa4221d9c",
"includeTrainee": false
}
]
},
{
"id": "8422dde5-221e-42a0-a1a0-e41381d69429",
"startTime": "2024-04-03T11:00:00.000Z",
"duration": 60,
"interviewId": "1a394a7e-b3f7-4b65-85d0-d4e8cb744d96",
"interviewName": "System design",
"interviewerRequirements": [
{
"id": "2b62d878-8ce3-472a-9048-a9a0e7b8d8d9",
"interviewerPoolId": "9988cfdf-a772-4741-ba0a-b11aa4221d9c",
"includeTrainee": true
},
{
"id": "ea0cb3d8-d80e-4d6f-a3d2-9b2d6089fdcd",
"interviewerPoolId": "9988cfdf-a772-4741-ba0a-b11aa4221d9c",
"includeTrainee": false
}
]
}
]
}
Of note here:
interviewerRequirements has 2 slightly different formats depending on whether the requirement is a pool or a fixed set of users. An array of length 1 would mean you must pick that user
An interviewer requirement represents one interviewer, and optionally one trainee. For the system design interview, we request 2 requirements with different ids but the same interviewer pool id. This represents requiring 2 users for this interview both from the same pool (and a trainee as one of those is true).
We would expect a response similar to:
{
"success": true,
"interviewRecommendations": [
{
"interviewRequirementId": "e63c444c-4802-47c1-9e02-cf37abc77ac4",
"interviewers": [
{
"interviewerRequirementId": "9ad4f37c-5407-4dec-b4fb-93b8f5061c1c",
"interviewerEmails": [
Want to print your doc?
This is not the way.
Try clicking the ⋯ next to your doc name or using a keyboard shortcut (
CtrlP
) instead.