メインコンテンツへスキップ
このガイドでは、何もない状態から候補者が面接の招待を受け取るまでを順を追って解説します。ステップは順番どおりに進めてください。各ステップは前のステップを土台にしています。
まずAPIキーが必要です。ダッシュボードの Developer → API Keys から作成してください。キーは iv_live_ で始まります。以下の各リクエストの x-api-key ヘッダーに設定し、<slug> をご自身のチームスラッグに置き換えてください。

​
構築するもの

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

​
ステップ 1 — 面接担当者（Interviewer）を作成する

これが 面接担当者（Interviewer） です。人格（パーソナリティ）と評価対象を決定します。 
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" }
  }'
👉 レスポンスから id をコピー してください。これを INTERVIEWER_ID と呼びます。

​
ステップ 2 — ロールを定義する

これが ロール（Role） です。職務の内容と合格基準を定めます。 
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_duration_minutes": 45,
    "default_difficulty": "advanced"
  }'
👉 id をコピー してください。これを ROLE_ID と呼びます。

​
ステップ 3 — ラウンドを追加する

これが ラウンド（Round） です。ロールと面接担当者を紐づけます。 
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"
  }'

​
ステップ 4 — 候補者を追加する

これが 参加者（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": "[email protected]",
    "external_id": "greenhouse-8821",
    "role_id": "ROLE_ID",
    "profile": { "title": "Software Engineer", "experienceLevel": "senior" }
  }'
👉 id をコピー してください。これを CANDIDATE_ID と呼びます。

​
ステップ 5 — 面接を送信する

これが セッション（session） です。招待メールは自動的に送信されます。 
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"
  }'
レスポンスには join_url が含まれ、招待メールが送信されたことが確認できます。

​
ステップ 6 — 結果を取得する

Jane が面接を終えると、彼女のスコアカードを2つの方法で取得できます。

おすすめ: Webhook

session.completed イベントを購読してください。面接が終わった瞬間に届きます。

シンプル: ポーリング

status が completed になるまで GET /api/v1/sessions/{id} を確認します。
ステップ 5 の idempotency_key があれば、リクエストを安全にリトライできます。仮に 2回実行されても、面接は2つではなく 1つ だけ作成されます。

​
これで完了です 🎉

フルの採用フローを構築できました。ラウンドをさらに追加するには、より大きい stage_order とより厳しい面接担当者を指定して ステップ 3 を繰り返してください。
最終更新日 2026年6月30日