Get Started
Quick Start
Create your first AI interview in under 5 minutes.
This guide walks you through creating an interview, handling the HITL approval flow, and receiving webhooks — from zero to a live candidate interview link.
Prerequisites
| Item | Value |
|---|---|
| API Base URL | https://mayaapi.teamcast.ai/api/v1 |
| API Key | Issued to your platform by Teamcast — set as X-API-Key header |
| Tenant ID | Identifies your customer — set as X-Tenant-ID header |
X-API-Key header and an X-Tenant-ID header. The API key authenticates your platform; the Tenant ID identifies the specific customer on whose behalf the request is made. Your webhook URL and signing secret are configured once per tenant in account settings — not passed per-request.Step 1 — Create an Interview
Submit a qualification-first interview request. Use candidateRef as the candidate identifier — no PII required. Providing qualifications[] with 2+ items lets Teamcast derive context without a separate job description. Pass your ATS application ID as externalId to make retries safe.
curl -X POST https://mayaapi.teamcast.ai/api/v1/integration/interviews \
-H "X-API-Key: your_api_key" \
-H "X-Tenant-ID: your_tenant_id" \
-H "Content-Type: application/json" \
-d '{
"candidateRef": "li_app_a1b2c3d4",
"candidateProfile": "8 years backend engineering, strong TypeScript background.",
"position": "Senior Software Engineer",
"level": "SENIOR",
"qualifications": [
"5+ years of production TypeScript experience",
"Demonstrated distributed systems design at scale",
"Strong async/concurrency patterns knowledge"
],
"companyName": "Acme Corp",
"externalId": "li_job_app_8821"
}'{
"runId": "run_1749123456_a1b2c3d4",
"interviewId": "interview-uuid",
"state": "VALIDATING_SKILLS",
"message": "Interview request accepted. Skill validation in progress.",
"dataQuality": "EXCELLENT"
}runId — you need it for all subsequent calls.Step 2 — Receive the Plan Webhook
When the Planner Agent finishes generating the interview plan, the system sends a webhook to your registered callbackUrl.
{
"event": "interview.plan_generated",
"runId": "run_1749123456_a1b2c3d4",
"interviewId": "interview-uuid",
"candidateRef": "li_app_a1b2c3d4",
"state": "PENDING",
"timestamp": "2024-01-15T10:45:00.000Z",
"data": {
"planId": "plan-uuid"
}
}Alternatively, poll status while waiting:
curl https://mayaapi.teamcast.ai/api/v1/integration/interviews/run_1749123456_a1b2c3d4 \
-H "X-API-Key: demo_api_key_..." \
-H "X-Tenant-ID: your_tenant_id"Step 3 — Review and Approve the Plan
Once the state is PENDING, the recruiter reviews the plan in the admin dashboard at /admin/approvals or via the API. This step is skipped when autoApprovePlans is enabled on your tenant.
curl -X POST https://mayaapi.teamcast.ai/api/v1/integration/interviews/run_1749123456_a1b2c3d4/plan/approve \
-H "X-API-Key: your_api_key" \
-H "X-Tenant-ID: your_tenant_id" \
-H "Content-Type: application/json" \
-d '{ "actorId": "li_recruiter_8821" }'{
"message": "Interview plan approved. Candidate interview link generated.",
"workflowState": "APPROVED",
"interviewLink": "{YOUR_APP_URL}/interview/join/eyJhbGc...",
"inmailDraft": {
"subject": "Senior Software Engineer Opportunity at Acme Corp — Interview Invitation",
"body": "Hi there,\n\nWe would love to invite you to complete an AI-powered interview for our Senior Software Engineer role at Acme Corp.\n\nPlease click the link below to begin:\n{YOUR_APP_URL}/interview/join/eyJhbGc...\n\nBest regards,\nThe Acme Corp Recruiting Team"
}
}Step 4 — Forward the Interview Link
Forward the interviewLink to the candidate via your own notification channel (LinkedIn InMail, email, etc.). The ready-to-use inmailDraft from the approve response has the link already substituted in the body. The candidate completes a device pre-check (camera and microphone) before joining the live AI interview session.
1. Candidate opens the interview link
2. Completes device pre-check (camera + microphone)
3. Joins the live Hiring Assistant sessionStep 5 — Review the Assessment
After the interview concludes, the AI Assessor Agent generates a structured report. You will receive an interview.assessment_pending webhook with the full assessment. Approve or reject via the API.
curl -X POST https://mayaapi.teamcast.ai/api/v1/integration/interviews/run_1749123456_a1b2c3d4/assessment/approve \
-H "X-API-Key: your_api_key" \
-H "X-Tenant-ID: your_tenant_id" \
-H "Content-Type: application/json" \
-d '{ "actorId": "li_recruiter_8821" }'{
"message": "Assessment approved. The full report has been sent via webhook.",
"workflowState": "ASSESSMENT_APPROVED"
}Full Workflow Summary
| Step | Actor | API Call | State After |
|---|---|---|---|
| 1 | Your system | POST /integration/interviews | VALIDATING_SKILLS |
| 2 | Planner Agent | (generates plan) | PENDING (or APPROVED if autoApprove) |
| 3 | Recruiter | POST .../plan/approve | APPROVED |
| 4 | Candidate | Opens interview link | IN_PROGRESS |
| 5 | Assessor Agent | (conducts and assesses) | ASSESSMENT_PENDING |
| 6 | Recruiter | POST .../assessment/approve | ASSESSMENT_APPROVED |
INFO_NEEDED state when data is incomplete.API Tryout
Use the interactive tryout below to make live API calls directly from your browser. Your API key is stored only in sessionStorage for this browser tab.
Credentials
Credentials saved to sessionStorage for this tab only. Never logged or sent to a third party.
Submit a new interview request. Returns a runId for subsequent calls.
Request Body