The candidate sees
Flip it and watch the branding payload follow.
realinterviews.ai Create interview

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.

Create interview
hello@realinterviews.ai No self-serve sign-up yet. Write to us and we will set up your test and live keys.
The whole backend
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.

01 · The endpoint

POST /v1/interviews

02 · Quickstart

Create your first interview.

  1. 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.

  2. 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.

  3. 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.

  4. Receive the write-up

    When the call ends you get interview.ended, then interview.completed with the write-up inside, or interview.needs_review. Fetch the transcript and recording whenever you like.

Create
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"
  }'
201 Created
{
  "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
interview.completed → your endpoint
{
  "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"
    }
  }
}
03 · Four ways in

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 inOn createYou give the candidateHow you test it
Hosted pageSetup: none live
channel: "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 live
channel: "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 live
channel: "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 request
channel: "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.
GET /v1/phone_numbers/test
{
  "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.

04 · Embedding

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.

POST /v1/interviews/int_7Kq2mW9xR4/session_token
{ "token": "st_7Fj2…", "expires_in": 300 }
HTML in your page
<!-- 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>
Try it from the browser console
(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); })();
05 · White-label

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.

POST /v1/accounts
{
  "name": "realinterviews.ai",
  "branding": {
    "colour": #1d6b5c,
    "logo_url": "https://…/mark.svg"
  },
  "retention": { "audio_days": 30, "transcript_days": 365 }
}
realinterviews.ai

Your interview for Registered Nurse – Emergency

An AI interviewer will ask about your experience. It takes about 15 minutes.

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

The same account, rendered. The sample employer uses a plain corporate blue so it is never mistaken for our own accent.
06 · Webhooks

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. Carries end_reason, talk_seconds and billable.
  • interview.completedThe write-up is ready, and included.
  • interview.needs_reviewThe interviewer could not reach a view; a person should listen. Half price.half price
  • interview.no_showNobody came.free
  • interview.failedSomething on our side failed.free
  • interview.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.
interview.ended → your endpoint
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
  }
}
Node · verify the signature
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.

07 · Reference

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/interviewscreate
  • GET /v1/interviews/{id}state, talk time, billable
  • POST …/{id}/cancel · POST …/{id}/call
  • GET …/{id}/report · /transcript · /recording
  • DELETE …/{id}/dataerase the candidate's data

Accounts and usage

  • POST /v1/accountsa sub-account per employer
  • GET /v1/usagethe month, by length and by sub-account
  • GET /v1/voicesthe voices, by language

Phone numbers

  • GET /v1/phone_numbers/testtest-call readiness
  • POST /v1/phone_numbersa dedicated number
  • POST /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.

Create interview
hello@realinterviews.ai
See pricing