Get Started

Quick Start

Create your first interview run against the Integration API in a few minutes.

1. Get an API key

From Settings → API Keys in the recruiter dashboard, create a key. The plaintext value (sk_live_<64 hex>) is shown exactly once — store it in a secret manager, not source control.

bash

curl -X POST https://devapi.teamcast.ai/api/v2/api-keys \
  -H "Authorization: Bearer <your_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ATS integration",
    "permissions": ["interview:create", "interview:read"]
  }'

# → { "id": "...", "apiKey": "sk_live_5f2c...", "keyPrefix": "sk_live_5f2c9a1b" }

2. Create an interview run

Platform-scoped keys must also pass X-Tenant-ID to select the customer tenant; tenant-owned keys omit it. external_id is your idempotency key — replaying the same value for the same tenant returns the existing run.

bash

curl -X POST https://devapi.teamcast.ai/api/v2/integration/interviews \
  -H "X-API-Key: sk_live_5f2c..." \
  -H "X-Tenant-ID: tnt_8a21b6" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "ats-req-4471",
    "candidate_ref": "cand-9021",
    "position": "Senior Backend Engineer",
    "level": "SENIOR",
    "skills": ["Node.js", "PostgreSQL", "distributed systems"],
    "job_description": "Own the payments service...",
    "duration_minutes": 40,
    "callback_url": "https://ats.example.com/webhooks/teamcast"
  }'

# → { "run_id": "run_1735689600_a1f9c2", "interview_id": "int_...",
#     "state": "GENERATING_PLAN", "message": "Interview run created." }

3. Receive webhook events

Register your callback URL once and Teamcast pushes a signed POST for every state change — no polling needed. You can also pass callback_url per-run in the create request (step 2 above) for a one-off override.

curl -X PUT https://devapi.teamcast.ai/api/v2/me/webhook-config \
  -H "X-API-Key: sk_live_5f2c..." \
  -H "X-Tenant-ID: tnt_8a21b6" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_url": "https://ats.example.com/webhooks/teamcast",
    "is_active": true,
    "events": []
  }'

# → { "callback_url": "...", "secret_hint": "****ab12", "is_active": true }

Store the secret returned on first registration — it is used to verify the X-Webhook-Signature header on every delivery.

interview.plan_generated — fires when the plan is ready for review

{
  "event": "interview.plan_generated",
  "run_id": "run_1735689600_a1f9c2",
  "interview_id": "int_7d2c...",
  "tenant_id": "tnt_8a21b6",
  "state": "PENDING",
  "timestamp": "2026-07-05T09:10:00.000Z",
  "data": {
    "plan_id": "pln_4e91...",
    "message": "plan ready for review"
  }
}

interview.approved — fires after plan approval, contains candidate link

{
  "event": "interview.approved",
  "run_id": "run_1735689600_a1f9c2",
  "interview_id": "int_7d2c...",
  "tenant_id": "tnt_8a21b6",
  "state": "APPROVED",
  "timestamp": "2026-07-05T09:11:00.000Z",
  "data": {
    "approved": true,
    "interview_link": "https://app.teamcast.ai/interview/join/tok_abc123",
    "inmail_draft": "Hi Sarah,\n\nWe'd like to invite you to an AI-powered interview..."
  }
}

interview.assessment_ready — fires after assessment is approved

{
  "event": "interview.assessment_ready",
  "run_id": "run_1735689600_a1f9c2",
  "interview_id": "int_7d2c...",
  "tenant_id": "tnt_8a21b6",
  "state": "ASSESSMENT_READY",
  "timestamp": "2026-07-05T09:12:03.000Z",
  "data": {
    "coverage_summary": {
      "overall_coverage": "partial",
      "gap_competencies": ["system design at scale"],
      "covered_count": 5,
      "total_count": 6
    },
    "highlights_count": 3,
    "lowlights_count": 1,
    "overall_coverage": "partial"
  }
}

Prefer polling? Use GET /integration/interviews/run_1735689600_a1f9c2 with your API key and check the state field. For full event payload shapes and signature verification see Integration API → Webhooks.

4. Approve the plan, then the assessment

Both gates default to requiring a human decision. Approving the plan invites the candidate; approving the assessment marks it delivered and fires interview.assessment_ready.

bash

curl -X POST https://devapi.teamcast.ai/api/v2/integration/interviews/run_1735689600_a1f9c2/plan/approve \
  -H "X-API-Key: sk_live_5f2c..." -H "X-Tenant-ID: tnt_8a21b6"

curl -X POST https://devapi.teamcast.ai/api/v2/integration/interviews/run_1735689600_a1f9c2/assessment/approve \
  -H "X-API-Key: sk_live_5f2c..." -H "X-Tenant-ID: tnt_8a21b6"

Prefer JSON-RPC? Every step above has an equivalent POST /a2a/task method (interview.create, interview.status, interview.approve, assessment.approve). See JSON-RPC reference.

Was this page helpful?

Previous← Introduction

NextWhat is Teamcast →