Introduction - intervyo.ai

intervyo.ai runs calibrated AI interviews — real-time voice conversations where the AI probes, follows up, scores against your rubric, and ships a transcript plus scorecard within ~2 minutes of the session ending. The same four building blocks power every use case, whether you’re screening engineers, certifying sales reps, or letting students rehearse. This page explains each one, the fields that matter, and how they change across use cases.

Two ways to do everything. You can build and run interviews entirely in the dashboard (no code) or over the API. Each concept page below shows both a Dashboard and an API path for creating it — pick whichever fits you. Prefer a guided walkthrough? Start with How it works, end to end.

The mental model

Configuration flows top-down. You define how the AI behaves, what it assesses, and which steps a candidate goes through — then attach people and run sessions.

Agent Profile        →  the interviewer (persona, scoring style, tone)
   └─ Evaluation Template   →  what to assess (role, skills, objective, pass bar)
        └─ Evaluation Stage      →  one step in the pipeline (uses an agent profile)
             └─ Participant            →  the person being evaluated
                  └─ Session                →  one AI interview → transcript + scorecard

Reuse is the point. One agent profile can power many templates; one template can have many stages; one participant can run many sessions. Define your calibration once, apply it everywhere.

Agent Profile

The interviewer’s personality and judgment. An agent profile decides how the AI introduces itself, how hard it pushes, and how it converts a conversation into a score. Attach a profile to a stage to control that step’s interview.

Key fields

name

string

required

Display name, e.g. "Senior Engineering Interviewer".

persona

string

required

How the AI introduces itself at the start, e.g. "Alex, a senior engineer at Acme." Sets the candidate’s first impression and the AI’s voice.

useCase

hiring | admissions | training | custom_api

required

Selects the recommendation vocabulary — hiring yields hire / no-hire, training yields ready / needs practice, and so on.

evaluationDimensions

array

required

The scoring axes: [{ name, description, weight }]. Weights must sum to 100. This is the rubric the AI grades against.

interaction

object

Conversation behavior: tone (friendly · professional · strict · challenging), style (structured · conversational · adaptive), difficulty (easy · medium · hard · adaptive), and probingDepth (low · medium · high).

scoring

object

How scores are computed: scale (0-10 · 0-5 · 0-100), scoringMethod (weighted_average · rule_based), and optional recommendationLogic.

context

object

Grounding for the AI: organizationContext, domainContext, scenarioContext — e.g. company background or the roleplay setup.

output

object

What the scorecard contains: includeTranscript, includeScoreBreakdown, includeRecommendation, includeImprovementFeedback (all default true).

How it changes per use case

Hiring
Training
Mock interview

Calibrated, slightly challenging, weighted toward role skills.

{
  "name": "Senior Backend Interviewer",
  "persona": "Alex, a staff engineer assessing backend depth.",
  "useCase": "hiring",
  "evaluationDimensions": [
    { "name": "System Design", "description": "Scalable architecture", "weight": 50 },
    { "name": "Coding",        "description": "Correctness & clarity",  "weight": 30 },
    { "name": "Communication", "description": "Explains trade-offs",    "weight": 20 }
  ],
  "interaction": { "tone": "professional", "difficulty": "hard", "probingDepth": "high" }
}

Supportive tone, coaching feedback emphasized over a pass/fail verdict.

{
  "name": "Sales Coach",
  "persona": "Sam, a sales enablement coach running a discovery drill.",
  "useCase": "training",
  "evaluationDimensions": [
    { "name": "Discovery",        "description": "Uncovers pain & budget", "weight": 40 },
    { "name": "Objection Handling","description": "Reframes pushback",      "weight": 40 },
    { "name": "Tone",             "description": "Confident, empathetic",   "weight": 20 }
  ],
  "interaction": { "tone": "friendly", "difficulty": "adaptive", "probingDepth": "medium" }
}

Realistic but encouraging — built for repetition and improvement feedback.

{
  "name": "FAANG Mock Interviewer",
  "persona": "Jordan, a big-tech interviewer running a practice round.",
  "useCase": "training",
  "evaluationDimensions": [
    { "name": "Problem Solving", "description": "Approach & edge cases", "weight": 60 },
    { "name": "Communication",   "description": "Thinks out loud",       "weight": 40 }
  ],
  "interaction": { "tone": "challenging", "difficulty": "hard", "probingDepth": "high" },
  "output": { "includeImprovementFeedback": true }
}

Evaluation Template

The blueprint for a role or assessment. A template describes what the AI should determine and the bar for success. Every participant and session belongs to a template.

Key fields

template_name

string

required

Display name, e.g. "Senior Backend Engineer".

use_case

hiring | admissions | training | custom_api

required

The category, which drives the recommendation vocabulary and defaults.

objective

string

required

The single thing the interview must determine, e.g. “Assess whether the candidate can own backend system design.”

success_outcome

enum

The verdict label: hire_no_hire, admit_reject, pass_fail, ready_needs_training, certified_not_certified, or custom. Auto-derived from use_case if omitted.

skills

string[]

Technical skills to probe, e.g. ["Go", "PostgreSQL", "Distributed Systems"].

soft_skills

string[]

Behavioral traits, e.g. ["Communication", "Ownership"].

requirements

string

What the candidate must demonstrate to pass — your bar, in plain language.

default_duration_minutes

integer

Default session length (default 30).

default_difficulty

beginner | intermediate | advanced | expert | adaptive

Question depth (default intermediate).

default_session_mode

enum

live_ai_interview, async_interview, roleplay_simulation, practice_session, or manual_review. Sets the interview format.

How it changes per use case

Field	Hiring	Training	Mock interview
`use_case`	`hiring`	`training`	`training`
`objective`	”Can they do the job?"	"Are they ready to perform?"	"Are they ready for the real thing?”
`success_outcome`	`hire_no_hire`	`ready_needs_training`	`pass_fail`
`default_session_mode`	`live_ai_interview`	`roleplay_simulation`	`practice_session`
`skills`	role-specific	competencies to build	target-role skills

Evaluation Stage

A single step within a template’s pipeline — e.g. Phone Screen → Technical → Final. Each stage runs its own interview with its own agent profile, duration, and pass threshold.

Key fields

evaluation_template_id

uuid

required

The parent template this stage belongs to.

stage_name

string

Display name shown to candidates, e.g. "Technical Screen".

stage_type

enum

ai_interview, roleplay_simulation, practice_session, manual_review, async_assessment, or final_review.

agent_profile_id

uuid

The agent profile that conducts this stage. This is where the interviewer’s persona and rubric plug in.

stage_order

integer

Position in the pipeline (0-based).

pass_threshold

number (0–100)

Minimum score required to pass this stage.

allow_retake

boolean

Whether a candidate can retry on failure (default false).

automation_rule

none | auto_advance | require_reviewer_approval

What happens on completion — advance automatically, or wait for a human.

How it changes per use case

Hiring
Training
Mock interview

Multiple gated stages, rising bar, human approval before the final round.

[
  { "stage_name": "Phone Screen", "stage_type": "ai_interview", "pass_threshold": 60, "automation_rule": "auto_advance" },
  { "stage_name": "Technical",    "stage_type": "ai_interview", "pass_threshold": 75, "automation_rule": "require_reviewer_approval" },
  { "stage_name": "Final",        "stage_type": "final_review",  "pass_threshold": 80 }
]

Repeatable drills with retakes; no gating — the goal is growth, not filtering.

[
  { "stage_name": "Discovery Drill",  "stage_type": "roleplay_simulation", "allow_retake": true, "pass_threshold": 70 },
  { "stage_name": "Objection Drill",  "stage_type": "roleplay_simulation", "allow_retake": true, "pass_threshold": 70 }
]

A single practice stage the candidate can repeat as often as they like.

[
  { "stage_name": "Mock Round", "stage_type": "practice_session", "allow_retake": true, "duration_minutes": 45 }
]

Participant

The person being evaluated — a candidate, trainee, or student. Create the participant first, then schedule sessions for them. A participant is scoped to a template, so the same email can exist as separate participants under different templates.

Key fields

name

string

required

Full name.

string

required

Email address — unique per account. The interview invite is sent here.

evaluation_template_id

uuid

The template (role / program) this participant is being evaluated against.

external_id

string

Your ATS / LMS / system ID. Echoed back in every webhook payload, so you can reconcile results without storing our IDs.

profile

object

{ title, organization, experienceLevel, location } — context the AI uses to tailor questions.

background

object

{ skills: string[], education, languages: string[] }.

resume_url

url

Publicly accessible resume — triggers vector extraction so the AI can reference it during the interview.

How it changes per use case

Hiring
Training
Mock interview

A candidate sourced from your ATS, with resume and role context.

{
  "name": "Jane Smith",
  "email": "jane@example.com",
  "external_id": "greenhouse-8821",
  "evaluation_template_id": "ce1cd564-...",
  "profile": { "title": "Software Engineer", "experienceLevel": "senior" },
  "resume_url": "https://.../jane-resume.pdf",
  "tags": ["senior", "backend"]
}

An internal rep enrolled for skill development; external_id is the HRIS ID.

{
  "name": "Carlos Reyes",
  "email": "carlos@yourco.com",
  "external_id": "workday-44120",
  "evaluation_template_id": "ce1cd564-...",
  "profile": { "title": "Account Executive", "organization": "West Region" },
  "tags": ["q3-cohort", "enablement"]
}

A self-serve student practicing; minimal data, identified by your app’s user ID.

{
  "name": "Priya Patel",
  "email": "priya@student.edu",
  "external_id": "user_98213",
  "evaluation_template_id": "ce1cd564-...",
  "profile": { "title": "New Grad", "experienceLevel": "entry" }
}

Session

The output — one AI interview for one participant, producing audio, a transcript, per-dimension scores, a recommendation, and authenticity signals. You schedule a session against a participant + template; the invite email goes out automatically. See Sessions.

Putting it together

Create an agent profile

Define the interviewer — persona, dimensions, tone.

Create an evaluation template

Describe the role/assessment and its objective.

Add stages

Add one or more stages, each pointing at an agent profile.

Add participants

Create the people to evaluate, bound to the template.

Schedule sessions

Schedule a session per participant — invites send automatically, scorecards arrive via webhook.

Where to next

Quickstart

Run your first AI interview in 5 minutes.

Authentication

Generate API keys and authenticate requests.

API Reference

Every endpoint with request builders and response examples.

Documentation is versioned with the platform — what you read here matches what’s deployed.

​The mental model

​Agent Profile

​Key fields

​How it changes per use case

​Evaluation Template

​Key fields

​How it changes per use case

​Evaluation Stage

​Key fields

​How it changes per use case

​Participant

​Key fields

​How it changes per use case

​Session

​Putting it together

​Where to next

Quickstart

Authentication

API Reference

The mental model

Agent Profile

Key fields

How it changes per use case

Evaluation Template

Key fields

How it changes per use case

Evaluation Stage

Key fields

How it changes per use case

Participant

Key fields

How it changes per use case

Session

Putting it together

Where to next