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 Agent (the interviewer) → Template (the role) → Stage (the round) → Participant (the candidate) → Session (the live interview)
Step 1 — Create the interviewer This is the agent profile . It decides the personality and what gets graded.
curl -X POST "https://www.intervyo.ai/api/v1/agent-profiles?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 AGENT_ID.
Step 2 — Describe the role This is the evaluation template . It says what the job is and the bar to pass.
curl -X POST "https://www.intervyo.ai/api/v1/evaluation-templates?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_duration_minutes": 45, "default_difficulty": "advanced" }'
👉 Copy the id . Call it TEMPLATE_ID.
Step 3 — Add the interview round This is the stage . It connects the template to your interviewer.
curl -X POST "https://www.intervyo.ai/api/v1/evaluation-stages?accountSlug=<slug>" \ -H "x-api-key: iv_live_your_key_here" \ -H "Content-Type: application/json" \ -d '{ "evaluation_template_id": "TEMPLATE_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", "agent_profile_id": "AGENT_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", "evaluation_template_id": "TEMPLATE_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", "evaluation_template_id": "TEMPLATE_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 agent profile. 
