Hiring, step by step

This guide walks you all the way from nothing to a candidate getting an interview invite. Follow the steps in order. Each step builds on the one before.

You need an API key first. Make one in the dashboard under Developer → API Keys. It starts with iv_live_. Put it in the x-api-key header on every request below, and replace <slug> with your team slug.

What you’ll build

Interviewer  →  Role  →  Round
   →  Participant (the candidate)  →  Session (the live interview)

Step 1 — Create the Interviewer

This is the Interviewer. It decides the personality and what gets graded.

curl -X POST "https://www.intervyo.ai/api/v1/interviewers?accountSlug=<slug>" \
  -H "x-api-key: iv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend Hiring Agent",
    "persona": "Alex, a staff engineer at our company.",
    "useCase": "hiring",
    "evaluationDimensions": [
      { "name": "System Design", "description": "Scalable architecture", "weight": 50 },
      { "name": "Coding",        "description": "Correct and clean",     "weight": 30 },
      { "name": "Communication", "description": "Explains trade-offs",   "weight": 20 }
    ],
    "interaction": { "tone": "professional", "difficulty": "hard", "probingDepth": "high" }
  }'

👉 Copy the id from the response. Call it INTERVIEWER_ID.

Step 2 — Describe the Role

This is the Role. It says what the job is and the bar to pass.

curl -X POST "https://www.intervyo.ai/api/v1/roles?accountSlug=<slug>" \
  -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.",
    "success_outcome": "hire_no_hire",
    "skills": ["Go", "PostgreSQL", "Distributed Systems"],
    "level": "Senior / 5+ years",
    "default_difficulty": "advanced"
  }'

👉 Copy the id. Call it ROLE_ID.

Step 3 — Add the Round

This is the Round. It connects the Role to your Interviewer.

curl -X POST "https://www.intervyo.ai/api/v1/rounds?accountSlug=<slug>" \
  -H "x-api-key: iv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "role_id": "ROLE_ID",
    "type": "technical",
    "stage_name": "Technical Screen",
    "stage_type": "ai_interview",
    "stage_order": 0,
    "duration_minutes": 45,
    "pass_threshold": 75,
    "automation_rule": "require_reviewer_approval",
    "interviewer_id": "INTERVIEWER_ID"
  }'

Step 4 — Add the candidate

This is the participant.

curl -X POST "https://www.intervyo.ai/api/v1/participants?accountSlug=<slug>" \
  -H "x-api-key: iv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "jane@example.com",
    "external_id": "greenhouse-8821",
    "role_id": "ROLE_ID",
    "profile": { "title": "Software Engineer", "experienceLevel": "senior" }
  }'

👉 Copy the id. Call it CANDIDATE_ID.

Step 5 — Send the interview

This is the session. The invite email goes out automatically.

curl -X POST "https://www.intervyo.ai/api/v1/sessions?accountSlug=<slug>" \
  -H "x-api-key: iv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "candidate_id": "CANDIDATE_ID",
    "role_id": "ROLE_ID",
    "stage": "screen",
    "idempotency_key": "greenhouse-8821-screen"
  }'

The response includes a join_url and confirms the invite was emailed.

Step 6 — Get the result

When Jane finishes, you get her scorecard two ways:

Best: webhooks

Listen for the session.completed event — it arrives the moment she’s done.

Simple: poll

Check GET /api/v1/sessions/{id} until status is completed.

The idempotency_key in Step 5 means you can safely retry the request. If it runs twice, you still get one interview, not two.

You’re done 🎉

You built a full hiring flow. To add more Rounds, repeat Step 3 with a higher stage_order and a tougher Interviewer.

Get Started

Concepts

Cookbook

Tutorials

Guides

MCP

What you’ll build

Step 1 — Create the Interviewer

Step 2 — Describe the Role

Step 3 — Add the Round

Step 4 — Add the candidate

Step 5 — Send the interview

Step 6 — Get the result

Best: webhooks

Simple: poll

You’re done 🎉

​What you’ll build

​Step 1 — Create the Interviewer

​Step 2 — Describe the Role

​Step 3 — Add the Round

​Step 4 — Add the candidate

​Step 5 — Send the interview

​Step 6 — Get the result

Best: webhooks

Simple: poll

​You’re done 🎉

What you’ll build

Step 1 — Create the Interviewer

Step 2 — Describe the Role

Step 3 — Add the Round

Step 4 — Add the candidate

Step 5 — Send the interview

Step 6 — Get the result

You’re done 🎉