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

# 採用フロー ステップバイステップ

> 面接担当者（Interviewer）、ロール、ラウンド、候補者、そしてライブ招待まで—フルの採用面接をゼロから1ステップずつ構築します。

このガイドでは、何もない状態から候補者が面接の招待を受け取るまでを順を追って解説します。ステップは順番どおりに進めてください。各ステップは前のステップを土台にしています。

<Note>
  まずAPIキーが必要です。ダッシュボードの **Developer → API
  Keys** から作成してください。キーは `iv_live_` で始まります。以下の各リクエストの
  `x-api-key` ヘッダーに設定し、`<slug>` をご自身のチームスラッグに置き換えてください。
</Note>

## 構築するもの

```text theme={null}
Interviewer  →  Role  →  Round
   →  Participant (the candidate)  →  Session (the live interview)
```

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

これが **面接担当者（Interviewer）** です。人格（パーソナリティ）と評価対象を決定します。

```bash theme={null}
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）** です。職務の内容と合格基準を定めます。

```bash theme={null}
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）** です。ロールと面接担当者を紐づけます。

```bash theme={null}
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）** です。

```bash theme={null}
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" }
  }'
```

👉 **`id` をコピー** してください。これを `CANDIDATE_ID` と呼びます。

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

これが **セッション（session）** です。招待メールは自動的に送信されます。

```bash theme={null}
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つの方法で取得できます。

<CardGroup cols={2}>
  <Card title="おすすめ: Webhook" icon="webhook" href="/jp/concepts/webhooks">
    `session.completed` イベントを購読してください。面接が終わった瞬間に届きます。
  </Card>

  <Card title="シンプル: ポーリング" icon="refresh-cw" href="/api-reference/sessions/get-sessions-id">
    `status` が `completed` になるまで `GET /api/v1/sessions/{id}` を確認します。
  </Card>
</CardGroup>

<Tip>
  ステップ 5 の `idempotency_key` があれば、リクエストを安全にリトライできます。仮に
  2回実行されても、面接は2つではなく **1つ** だけ作成されます。
</Tip>

## これで完了です 🎉

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