> ## 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.
# Roles
> Blueprints for a role or assessment — rounds, rubrics, AI interviewer, application flow.
A **Role** is the blueprint for what you're hiring or assessing for. It defines:
* **Rounds** — how many steps (single-round screen, multi-round funnel). See
[Rounds](/en/concepts/rounds).
* **Rubrics per round** — what gets scored
* **The Interviewer** — which AI persona runs each round (name, voice, tone).
See [Interviewers](/en/concepts/interviewers).
* **The application flow** — public apply URL, HR approval gate, OTP
* **Branding** — logo, colors candidates see during the interview
Once configured, the Role can be shared with thousands of candidates
or invoked programmatically — the rubric and conversational behavior are
identical every time.
## Create one, step by step
Create a template in the dashboard or over the API — same result either way.
In the team dashboard, click **Roles** in the left sidebar.
Click **New** (or **Create Role**).
Fill in the **Name**, pick the **Use case** (Hiring, Admissions,
Training…), and write the **Objective** — the one thing the interview
should determine.
List the **Skills** to probe and the **Requirements** a candidate must
meet to pass. Set the default **difficulty**. (Duration is set per
Round, not on the Role.)
Save the Role, then add one or more
[Rounds](/en/concepts/rounds) to it.
Set `template_name` and `use_case`. Add a `description` and `objective`.
Set `skills`, `requirements`, and `default_difficulty`. (Duration is
configured per Round via `create_round`, not on the Role.)
```bash theme={null}
curl -X POST "https://www.intervyo.ai/api/v1/roles?accountSlug=" \
-H "x-api-key: iv_live_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"template_name": "Senior Backend Engineer",
"use_case": "hiring",
"description": "Backend role focused on distributed systems.",
"objective": "Decide if the candidate can own backend system design.",
"skills": ["Go", "PostgreSQL", "Distributed Systems"],
"level": "Senior / 5+ years",
"default_difficulty": "advanced"
}'
```
The response returns the template `id`. Use it when creating stages and
participants.
## A filled-in example (no code)
Here's a complete **"Customer Support Specialist"** Role you could create in the
dashboard in a couple of minutes — no technical knowledge needed.
| Field | What to type |
| ---------------- | ------------------------------------------------------------------------------- |
| **Name** | `Customer Support Specialist` |
| **Use case** | `Hiring` |
| **Objective** | `Can this person calm an upset customer and resolve the issue clearly?` |
| **Skills** | `Communication, Empathy, Problem-solving, Product knowledge` |
| **Requirements** | `Stays calm under pressure, follows policy, confirms the fix with the customer` |
| **Difficulty** | `Easy` |
Save it, then add the **Rounds** — for this Role, two is plenty:
| # | Round | Interviewer | Pass mark |
| - | ---------------- | --------------------------------------------- | --------- |
| 1 | Screening | Friendly Screener | 60 |
| 2 | Support Roleplay | Support Roleplay (AI plays an upset customer) | 70 |
That's a complete, working setup. Add candidates (or share the apply link) and the
AI handles the interviews. For more ready-made setups, see the
[Cookbook](/en/cookbook/overview).
## When to use one template vs many
The default. Each open role gets its own template so the rubric and AI
persona are tuned to the work. Same person applying to two roles gets
two participant rows — one per template.
For L\&D, certifications, or admissions — define stages, pass
thresholds, and the AI persona once per cohort. Participants progress
through automatically.
Templates are cheap. If you're hesitating between forking and reusing,
fork. Two templates with subtly different rubrics is easier to reason
about than one template with conditional scoring.
## Single-stage vs multi-stage
The simplest template has **one stage** — a single AI interview, scored,
done. That's the right shape for most first-round screens.
For programs and senior hiring, chain stages:
```text theme={null}
Stage 1: Phone Screen Stage 2: Technical Stage 3: Behavioral
────────────────────────► ────────────────────────► ────────────────────
Communication: 8.5 Code quality: 7.8 Ownership: 8.2
Domain: 7.0 Trade-offs: 8.1 Collaboration: 7.5
passed → auto-advance passed → auto-advance passed → recommend
failed → auto-decline failed → auto-decline failed → archive
```
Each stage has:
* Its own rubric and pass thresholds
* Its own AI persona (a screening persona for stage 1, a senior engineer
persona for stage 2)
* Its own question bank or coding-problem pool
The platform routes candidates between stages automatically based on
pass/fail decisions. Recruiters can override (promote a borderline
candidate, hold a candidate pending review) but the default flow needs
no human in the loop.
## Branding + persona
Two surfaces let you make the interview feel like yours:
Name your AI ("Mia", "Aki", "Alex") and pick a voice, tone, and
register from the persona library. Candidates ask for the interviewer
by name; you keep continuity across interviews.
Configure per template via the **Persona** tab on the template detail
page, or set `personaId` on the API.
Logo, colors, fonts, and (optionally) custom domain. Candidates see
your brand from the apply page through the interview and into the
feedback email — no third-party watermark.
Workspace-level by default; enterprise plans support per-template
overrides for multi-brand workflows (agencies, multi-product orgs).
## The public apply flow
Every template ships with a **public apply URL** at
`https://intervyo.ai/apply/`. Candidates:
1. Open the URL
2. Verify their email with a 6-digit OTP
3. Upload a CV (PDF / Word / scan)
4. Get screened by the AI immediately
Apply URLs are **rotatable** in one click from the template detail page —
the old URL stops working immediately if compromised.
You can require **HR approval** between application and interview. With
approval on:
* The candidate's application lands in the panel with status `pending`
* Recruiter reviews CV match score + skim the resume
* Approve → candidate gets the interview link
* Reject → candidate gets a polite decline
With approval off (auto-approve), the apply page hands the interview link
to the candidate immediately. Use auto-approve for high-volume roles
where reviewing every CV is the bottleneck.
## Per-template participant model
Each candidate is bound to **one template at a time**. The same email
applying to two templates produces two participant rows — one per
template. This keeps each role's funnel clean and prevents accidental
overwrites.
You can move a participant between templates from the participants page —
the platform creates an approved application row on the new template so
they show up in that template's panel. See the participant edit
flow in the workspace UI for the move action.
## Sharing candidate profiles
Templates support two share modes:
* **Single-candidate share** — one URL that shows one candidate's
interview history. For sharing with hiring panels or panels of one.
* **Multi-candidate share** — one URL that bundles multiple candidates
side-by-side, ranked. For client submissions in agency workflows.
Both modes:
* Expire on a configurable date (7 / 30 / 90 / 180 days)
* Are revocable in one click
* Show view counts and last-viewed timestamps
* Always show the **latest** session per stage (so retries surface
automatically)
* Need no login on the recipient side
Configure shares from the template's **Share** panel on the detail page.