> ## Documentation Index
> Fetch the complete documentation index at: https://intervyo.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Understand intervyo.ai's core building blocks — Interviewers, Roles, Rounds, and participants — and how they map to hiring, training, and mock interviews.

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

<Note>
  **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](/en/guides/how-it-works).
</Note>

## In plain English

Think of how a real company interviews someone:

* A **Role** is the *job you're hiring (or assessing) for* — "Customer Support Specialist", "ServiceNow Engineer", "Account Executive". It says **what** good looks like.
* A **Round** is *one step* in that job's interview — a phone screen, a technical round, a final. A Role can have one Round or several.
* An **Interviewer** is the *person who runs a Round* — here, an AI persona with a scorecard. You build one once (e.g. an "ITOM Specialist" or a "Friendly Screener") and **reuse it** in any Round of any Role.

> **A Role has Rounds; each Round is run by an Interviewer.**

You don't need to be technical to set this up — you describe the Role in plain words, add the Rounds you want, and pick an Interviewer for each. Then you add people and the AI does the interviews.

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

```text theme={null}
Role                 →  what to assess (the job, skills, objective, pass bar)
   └─ Round               →  one step in the interview (screen, technical, final)
        └─ Interviewer         →  the AI persona + scorecard that runs the Round
   └─ Participant         →  the person being evaluated, attached to the Role
        └─ Session             →  one AI interview → transcript + scorecard
```

<Info>
  **Reuse is the point.** One Interviewer can run Rounds across many Roles; one Role can have many Rounds; one participant can run many sessions. Define your calibration once, apply it everywhere.
</Info>

***

## Interviewer

*(API field name: `agent_profile`)*

The **interviewer's personality and judgment**. An Interviewer decides how the AI introduces itself, how hard it pushes, and how it converts a conversation into a score. Attach an Interviewer to a Round to control that step's interview.

### Key fields

<ParamField path="name" type="string" required>
  Display name, e.g. `"Senior Engineering Interviewer"`.
</ParamField>

<ParamField path="persona" type="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.
</ParamField>

<ParamField path="useCase" type="hiring | admissions | training | custom_api" required>
  Selects the recommendation vocabulary — `hiring` yields *hire / no-hire*, `training` yields *ready / needs practice*, and so on.
</ParamField>

<ParamField path="evaluationDimensions" type="array" required>
  The scoring axes: `[{ name, description, weight }]`. **Weights must sum to 100.** This is the rubric the AI grades against.
</ParamField>

<ParamField path="interaction" type="object">
  Conversation behavior: `tone` (friendly · professional · strict · challenging), `style` (structured · conversational · adaptive), `difficulty` (easy · medium · hard · adaptive), and `probingDepth` (low · medium · high).
</ParamField>

<ParamField path="scoring" type="object">
  How scores are computed: `scale` (0-10 · 0-5 · 0-100), `scoringMethod` (weighted\_average · rule\_based), and optional `recommendationLogic`.
</ParamField>

<ParamField path="context" type="object">
  Grounding for the AI: `organizationContext`, `domainContext`, `scenarioContext` — e.g. company background or the roleplay setup.
</ParamField>

<ParamField path="output" type="object">
  What the scorecard contains: `includeTranscript`, `includeScoreBreakdown`, `includeRecommendation`, `includeImprovementFeedback` (all default `true`).
</ParamField>

### How it changes per use case

<Tabs>
  <Tab title="Hiring">
    Calibrated, slightly challenging, weighted toward role skills.

    ```json theme={null}
    {
      "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" }
    }
    ```
  </Tab>

  <Tab title="Training">
    Supportive tone, coaching feedback emphasized over a pass/fail verdict.

    ```json theme={null}
    {
      "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" }
    }
    ```
  </Tab>

  <Tab title="Mock interview">
    Realistic but encouraging — built for repetition and improvement feedback.

    ```json theme={null}
    {
      "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 }
    }
    ```
  </Tab>
</Tabs>

***

## Role

*(API field name: `evaluation_template`)*

The **blueprint for what you're hiring or assessing for**. A Role describes what the AI should determine and the bar for success. Every participant and session belongs to a Role.

### Key fields

<ParamField path="template_name" type="string" required>
  Display name, e.g. `"Senior Backend Engineer"`.
</ParamField>

<ParamField path="use_case" type="hiring | admissions | training | custom_api" required>
  The category, which drives the recommendation vocabulary and defaults.
</ParamField>

<ParamField path="objective" type="string" required>
  The single thing the interview must determine, e.g. *"Assess whether the candidate can own backend system design."*
</ParamField>

<ParamField path="success_outcome" type="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.
</ParamField>

<ParamField path="skills" type="string[]">
  Technical skills to probe, e.g. `["Go", "PostgreSQL", "Distributed Systems"]`.
</ParamField>

<ParamField path="soft_skills" type="string[]">
  Behavioral traits, e.g. `["Communication", "Ownership"]`.
</ParamField>

<ParamField path="requirements" type="string">
  What the candidate must demonstrate to pass — your bar, in plain language.
</ParamField>

<ParamField path="default_difficulty" type="beginner | intermediate | advanced | expert | adaptive">
  Question depth (default `intermediate`).
</ParamField>

<ParamField path="default_session_mode" type="enum">
  `live_ai_interview`, `async_interview`, `roleplay_simulation`, `practice_session`, or `manual_review`. Sets the interview format.
</ParamField>

### 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                   |

***

## Round

*(API field name: `evaluation_stage`)*

A **single step within a Role's pipeline** — e.g. *Phone Screen → Technical → Final*. Each Round runs its own interview with its own Interviewer, duration, and pass threshold.

### Key fields

<ParamField path="role_id" type="uuid" required>
  The Role this Round belongs to.
</ParamField>

<ParamField path="stage_name" type="string">
  Display name shown to candidates, e.g. `"Technical Screen"`.
</ParamField>

<ParamField path="stage_type" type="enum">
  `ai_interview`, `roleplay_simulation`, `practice_session`, `manual_review`, `async_assessment`, or `final_review`.
</ParamField>

<ParamField path="interviewer_id" type="uuid">
  The Interviewer that conducts this Round. This is where the persona and rubric plug in.
</ParamField>

<ParamField path="stage_order" type="integer">
  Position in the pipeline (0-based).
</ParamField>

<ParamField path="pass_threshold" type="number (0–100)">
  Minimum score required to pass this stage.
</ParamField>

<ParamField path="allow_retake" type="boolean">
  Whether a candidate can retry on failure (default `false`).
</ParamField>

<ParamField path="automation_rule" type="none | auto_advance | require_reviewer_approval">
  What happens on completion — advance automatically, or wait for a human.
</ParamField>

### How it changes per use case

<Tabs>
  <Tab title="Hiring">
    Multiple gated stages, rising bar, human approval before the final round.

    ```json theme={null}
    [
      { "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 }
    ]
    ```
  </Tab>

  <Tab title="Training">
    Repeatable drills with retakes; no gating — the goal is growth, not filtering.

    ```json theme={null}
    [
      { "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 }
    ]
    ```
  </Tab>

  <Tab title="Mock interview">
    A single practice stage the candidate can repeat as often as they like.

    ```json theme={null}
    [
      { "stage_name": "Mock Round", "stage_type": "practice_session", "allow_retake": true, "duration_minutes": 45 }
    ]
    ```
  </Tab>
</Tabs>

***

## 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 Role, so the same email can exist as separate participants under different Roles.

### Key fields

<ParamField path="name" type="string" required>
  Full name.
</ParamField>

<ParamField path="email" type="string" required>
  Email address — unique per account. The interview invite is sent here.
</ParamField>

<ParamField path="role_id" type="uuid">
  The Role this participant is being evaluated against.
</ParamField>

<ParamField path="external_id" type="string">
  Your ATS / LMS / system ID. **Echoed back in every webhook payload**, so you can reconcile results without storing our IDs.
</ParamField>

<ParamField path="profile" type="object">
  `{ title, organization, experienceLevel, location }` — context the AI uses to tailor questions.
</ParamField>

<ParamField path="background" type="object">
  `{ skills: string[], education, languages: string[] }`.
</ParamField>

<ParamField path="resume_url" type="url">
  Publicly accessible resume — triggers vector extraction so the AI can reference it during the interview.
</ParamField>

<ParamField path="tags" type="string[]">
  Arbitrary labels for filtering, e.g. `["senior", "remote"]`.
</ParamField>

### How it changes per use case

<Tabs>
  <Tab title="Hiring">
    A candidate sourced from your ATS, with resume and role context.

    ```json theme={null}
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "external_id": "greenhouse-8821",
      "role_id": "ce1cd564-...",
      "profile": { "title": "Software Engineer", "experienceLevel": "senior" },
      "resume_url": "https://.../jane-resume.pdf",
      "tags": ["senior", "backend"]
    }
    ```
  </Tab>

  <Tab title="Training">
    An internal rep enrolled for skill development; `external_id` is the HRIS ID.

    ```json theme={null}
    {
      "name": "Carlos Reyes",
      "email": "carlos@yourco.com",
      "external_id": "workday-44120",
      "role_id": "ce1cd564-...",
      "profile": { "title": "Account Executive", "organization": "West Region" },
      "tags": ["q3-cohort", "enablement"]
    }
    ```
  </Tab>

  <Tab title="Mock interview">
    A self-serve student practicing; minimal data, identified by your app's user ID.

    ```json theme={null}
    {
      "name": "Priya Patel",
      "email": "priya@student.edu",
      "external_id": "user_98213",
      "role_id": "ce1cd564-...",
      "profile": { "title": "New Grad", "experienceLevel": "entry" }
    }
    ```
  </Tab>
</Tabs>

***

## 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](/en/concepts/sessions).

## Putting it together

<Steps>
  <Step title="Create an agent profile">
    Define the interviewer — persona, dimensions, tone.
  </Step>

  <Step title="Create an Interviewer">
    Define the AI persona — its dimensions, tone, and scoring.
  </Step>

  <Step title="Create an evaluation template">
    Describe the role/assessment and its objective.
  </Step>

  <Step title="Create a Role">
    Describe the job/assessment and its objective.
  </Step>

  <Step title="Add stages">
    Add one or more stages, each pointing at an agent profile.
  </Step>

  <Step title="Add Rounds">
    Add one or more Rounds to the Role, each pointing at an Interviewer.
  </Step>

  <Step title="Add participants">
    Create the people to evaluate, bound to the template.
  </Step>

  <Step title="Add participants">
    Create the people to evaluate, bound to the Role.
  </Step>

  <Step title="Schedule sessions">
    Schedule a session per participant — invites send automatically, scorecards arrive via webhook.
  </Step>
</Steps>

## Where to next

<CardGroup cols={3}>
  <Card title="Quickstart" icon="rocket" href="/en/quickstart">
    Run your first AI interview in 5 minutes.
  </Card>

  <Card title="Authentication" icon="key" href="/en/authentication">
    Generate API keys and authenticate requests.
  </Card>

  <Card title="API Reference" icon="terminal" href="/api-reference/introduction">
    Every endpoint with request builders and response examples.
  </Card>
</CardGroup>

<Note>
  Documentation is versioned with the platform — what you read here matches what's deployed.
</Note>