For developers · JSON over HTTPS
One post. One hook.
Your server creates the interview and handles the webhook that returns the result. That is the whole backend. Then pick how the candidate takes it — a link, a tag in your page, or a phone number — and test it in test mode for free.
hello@realinterviews.ai
No self-serve sign-up yet. Write to us and we will set up your test and live keys.
POST /v1/interviews
↳ 201 { "candidate_url": "…" }
interview.completed
↳ your webhook, signed
Base URL api.realinterviews.ai/v1 · keys are server-side only · every webhook carries RealInterviews-Signature.
POST /v1/interviews
api.realinterviews.ai/v1Base URL. JSON over HTTPS.Authorization: Bearer vk_test_…Test and live keys. Server-side only, never in the browser.Idempotency-KeySend one and a create is safe to retry.RealInterviews-SignatureHMAC-SHA256 on every webhook. Verified in six lines, below.
Create your first interview.
Get a test key
Request access and we will set up your account. Copy the key that starts with
vk_test_. Keep it on your server only. Test interviews are real voice calls, free and never billed.Create the interview
Send the role, one to eight requirements in plain sentences, a length and a channel. Write requirements the way a hiring manager would say them; the interviewer turns each into questions and never reads them out word for word.
Send the candidate the link
The response carries
candidate_url. Send it through your own email or SMS, under your customer's name. For phone, it carries the number and the six-digit code instead.Receive the write-up
When the call ends you get
interview.ended, theninterview.completedwith the write-up inside, orinterview.needs_review. Fetch the transcript and recording whenever you like.
curl https://api.realinterviews.ai/v1/interviews \
-H "Authorization: Bearer $REALINTERVIEWS_KEY" \
-H "Idempotency-Key: app_88213-screen" \
-H "Content-Type: application/json" \
-d '{
"role": { "title": "Registered Nurse – Emergency" },
"requirements": [
"Has worked in an emergency department",
"Can describe triage under pressure",
"Holds current AHPRA registration"
],
"length_minutes": 15,
"channel": "web",
"language": "en-AU",
"candidate": { "name": "Priya Raman" },
"external_id": "app_88213"
}'
{
"id": "int_7Kq2mW9xR4",
"object": "interview",
"mode": "test",
"status": "waiting",
"channel": "web",
"length_minutes": 15,
"candidate_url": "https://talk.realinterviews.ai/…",
"external_id": "app_88213"
}
// send candidate_url to the candidate yourself
{
"id": "evt_2Pd81cLq",
"type": "interview.completed",
"created_at": "2026-11-18T03:39:20Z",
"data": {
"id": "int_7Kq2mW9xR4",
"external_id": "app_88213",
"status": "completed",
"report": {
"findings": [
{ "requirement": "Has worked in an emergency department",
"finding": "met",
"evidence": [
{ "turn": 4, "at_ms": 72000,
"quote": "Two and a half years at Royal Melbourne ED…" }
] }
],
"decided_by": "advisory"
}
}
}
Same backend. Four ways for the candidate. Each one has a test.
The channel on create is web or phone; a phone interview also says direction. Everything else stays the same, so you can mix them per candidate.
| Way in | On create | You give the candidate | How you test it |
|---|---|---|---|
| Hosted pageSetup: none | livechannel: "web" |
candidate_url, in your own email or SMS. |
Create one with your test key and open the link yourself. It is a real voice interview, free in test mode. |
| EmbeddedSetup: about half a day | livechannel: "web" then POST /v1/interviews/{id}/session_token |
Nothing: the interview is already in your page. | Paste the browser-console snippet into any page; it floats a button at the bottom-right. Then add the script tag to your real page. |
| Candidate calls inSetup: none | livechannel: "phone", direction: "inbound" |
The number and the six-digit code, from dial_in, with the invite text that carries the terms. |
GET /v1/phone_numbers/test returns the shared test number, the code of your newest open test interview and the steps left. Dial it and enter the code. |
| We call the candidateSetup: none | on requestchannel: "phone", direction: "outbound", the mobile and a time |
A heads-up text an hour before, then the call, 8am–8pm in their time zone. | With a test key, realinterviews.ai only ever calls numbers you have verified: POST /v1/phone_numbers/verified, confirm the code, then a test call to yourself. |
{
"object": "phone_test",
"status": "ready",
"steps": [
{ "key": "test_number",
"label": "Shared test number is ready", "done": true },
{ "key": "test_interview",
"label": "You have an open test interview", "done": true },
{ "key": "dial",
"label": "Dial the number and enter the code", "done": false }
]
}
Phone, in five countries to start
Inbound and outbound phone interviews run for numbers in Australia, New Zealand, the United Kingdom, the United States and Canada. A number outside those is refused on create, so you find out before the candidate does.
Every phone call opens with the same fixed notice. On an inbound call, entering the code is the candidate's agreement; nothing is recorded, and nothing is billed, before a valid code. See what the candidate hears.
One tag, in your page, under their brand.
Mint a short-lived token on your server, render the tag where the interview should sit, and embed.js draws it in place. Your secret key never reaches the browser.
data-target="#id"draws into that element instead.data-mode="float"attaches a button at the bottom-right, so you can add it without changing your layout.The token must be used within five minutes and is good for one interview; once the page opens, it lasts for that interview.
{ "token": "st_7Fj2…", "expires_in": 300 }
<!-- draws in place where the tag sits -->
<script src="https://js.realinterviews.ai/v1/embed.js"
data-interview="int_7Kq2mW9xR4"
data-token="st_7Fj2…" async></script>
(function(){ var s=document.createElement('script');
s.src='https://js.realinterviews.ai/v1/embed.js';
s.dataset.interview='int_…'; s.dataset.token='st_test_…';
s.dataset.mode='float'; document.body.appendChild(s); })();
The candidate sees realinterviews.ai. Never us.
An account carries a name, a mark and one colour. The interview page, the invite and the voice all use them: the page takes the colour, the interviewer says "the AI interviewer for realinterviews.ai". realinterviews.ai's own name does not appear.
Running interviews for many employers? Create a sub-account per employer with POST /v1/accounts, each with its own branding and retention, and pass it on create. Anything you leave out inherits from your root account. Usage is split by sub-account, so each employer's interviews can be billed on.
Flip the switch at the top of the page: the colour in the payload on the right is the colour this whole page is wearing.
{
"name": "realinterviews.ai",
"branding": {
"colour": #1d6b5c,
"logo_url": "https://…/mark.svg"
},
"retention": { "audio_days": 30, "transcript_days": 365 }
}
Your interview for Registered Nurse – Emergency
It's recorded for the hiring team to listen to. A person makes every decision. There is no score. The audio is kept 30 days, the transcript 12 months. You can stop at any time.
Need a different format? Ask realinterviews.ai
Signed, retried, and never the only way to find out.
Every event is a POST to your endpoint with a RealInterviews-Signature header. Answer with any 2xx within ten seconds. Failed deliveries are retried for three days with growing gaps. Events can arrive more than once and out of order, so use the event id to skip duplicates and fetch the interview if order matters.
interview.startedThe candidate agreed and the interview began.interview.endedThe call ended. Carriesend_reason,talk_secondsandbillable.interview.completedThe write-up is ready, and included.interview.needs_reviewThe interviewer could not reach a view; a person should listen. Half price.half priceinterview.no_showNobody came.freeinterview.failedSomething on our side failed.freeinterview.opted_outThe candidate said stop, pressed 9, or replied STOP to a text.interview.accommodation_requestedThe candidate asked for a different format. Sent once, with their note.
RealInterviews-Signature: t=1795403960,v1=5f2b…
{
"id": "evt_2Pd81cLq",
"type": "interview.ended",
"created_at": "2026-11-18T03:39:20Z",
"data": {
"id": "int_7Kq2mW9xR4",
"external_id": "app_88213",
"end_reason": "all_covered",
"talk_seconds": 462,
"billable": true
}
}
import crypto from "node:crypto";
export function verifyRealInterviews(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(",").map(p => p.split("=")));
const age = Date.now() / 1000 - Number(parts.t);
if (age > 300) return false; // older than 5 minutes
const expected = crypto.createHmac("sha256", secret)
.update(parts.t + "." + rawBody).digest("hex");
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}
Every event can be resent from the dashboard, and GET /v1/interviews/{id} always has the current state, so a missed webhook never loses a result.
Everything the API does, in one list.
The full reference, with every field, lives in the API docs. This is the map.
Interviews
POST /v1/interviewscreateGET /v1/interviews/{id}state, talk time, billablePOST …/{id}/cancel · POST …/{id}/callGET …/{id}/report · /transcript · /recordingDELETE …/{id}/dataerase the candidate's data
Accounts and usage
POST /v1/accountsa sub-account per employerGET /v1/usagethe month, by length and by sub-accountGET /v1/voicesthe voices, by language
Phone numbers
GET /v1/phone_numbers/testtest-call readinessPOST /v1/phone_numbersa dedicated numberPOST /v1/phone_numbers/verifiedverify your own number for outbound tests
Create interview.
A test key, one request, one real voice call. Free, and never billed.