Intervue — API documentation

Quickstart

Three calls take you from a new key to candidates holding their interview links.

01
Create a key
Open API access in your dashboard and create a key. Use a test key while you build.
02
Check the key
Call GET /auth/verify/ to confirm the key works.
03
Create an interview, then add candidates
Create the interview once, then send candidates to it one at a time or in bulk.

Authentication

Send your key in the Authorization header as a bearer token on every request. All requests use HTTPS and JSON.

Keep keys on your server. Never put a key in browser or mobile app code. If a key leaks, delete it from API access and create a new one.

API access is part of the Enterprise plan. Talk to us to turn it on.

Verify your key

GET/auth/verify/

Returns 200 when the key is valid. Use it as a health check when your integration starts.

curl https://intervue.ai/api/v1/auth/verify/ \
  -H "Authorization: Bearer intv_live_xxxxxxxx"

import requests

r = requests.get(
    "https://intervue.ai/api/v1/auth/verify/",
    headers={"Authorization": "Bearer intv_live_xxxxxxxx"},
)
print(r.status_code, r.json())

const res = await fetch("https://intervue.ai/api/v1/auth/verify/", {
  headers: { Authorization: "Bearer intv_live_xxxxxxxx" },
});
console.log(res.status, await res.json());

Response200 OK

{
  "valid": true
}

Create an interview

POST/interviews/

Creates an interview that candidates can be added to. Keep the returned id; you need it to add candidates.

title string, required

The interview name your team will see.

curl -X POST https://intervue.ai/api/v1/interviews/ \
  -H "Authorization: Bearer intv_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"title": "Senior Backend Engineer"}'

r = requests.post(
    "https://intervue.ai/api/v1/interviews/",
    headers={"Authorization": "Bearer intv_live_xxxxxxxx"},
    json={"title": "Senior Backend Engineer"},
)
interview_id = r.json()["id"]

const res = await fetch("https://intervue.ai/api/v1/interviews/", {
  method: "POST",
  headers: {
    Authorization: "Bearer intv_live_xxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ title: "Senior Backend Engineer" }),
});
const { id } = await res.json();

Response201 Created

{
  "id": "9b2f6c1e-4d7a-4f0e-8a31-5c6d2e1f7a90",
  "title": "Senior Backend Engineer"
}

Add candidates

POST/interviews/:interview_id/candidates/

Adds candidates to an interview. Send one candidate or many in the same request. Each candidate gets a personal interview link.

candidates array, required

The people to invite.

candidates[].name string, required

The candidate’s full name.

candidates[].email string, required

Where the interview link is sent.

curl -X POST https://intervue.ai/api/v1/interviews/$INTERVIEW_ID/candidates/ \
  -H "Authorization: Bearer intv_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"candidates": [{"name": "Ama Mensah", "email": "ama@example.com"}, {"name": "Kofi Boateng", "email": "kofi@example.com"}]}'

r = requests.post(
    f"https://intervue.ai/api/v1/interviews/{interview_id}/candidates/",
    headers={"Authorization": "Bearer intv_live_xxxxxxxx"},
    json={"candidates": [
        {"name": "Ama Mensah", "email": "ama@example.com"},
        {"name": "Kofi Boateng", "email": "kofi@example.com"},
    ]},
)

const res = await fetch(`https://intervue.ai/api/v1/interviews/${id}/candidates/`, {
  method: "POST",
  headers: {
    Authorization: "Bearer intv_live_xxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ candidates: [
    { name: "Ama Mensah", email: "ama@example.com" },
    { name: "Kofi Boateng", email: "kofi@example.com" },
  ] }),
});

Response201 Created

{
  "created": 2,
  "candidates": [
    {
      "id": "c41d8e52-0b6a-4c2f-9d17-7e3a5b8f1a26",
      "email": "ama@example.com",
      "interview_link": "https://intervue.ai/interview/…"
    }
  ]
}

Errors

Failed requests return a standard status code and a JSON body that says what went wrong.

400 Bad request

A field is missing or invalid.

401 Unauthorized

The key is missing, wrong, or deleted.

403 Forbidden

Your plan does not include API access.

404 Not found

The interview does not exist in your organisation.

Stuck on an integration?

Write to us with what you are building and an engineer will reply.

Email the team