Teamcast Maya Documentation

Integration API

REST endpoints and webhook notifications for connecting your ATS or HR platform to the AI Interview System.

The Integration API gives external systems — ATS platforms, HR tools, and hiring portals — a clean REST interface to create and manage AI-powered interviews. Teamcast acts as a targeted qualification validation layer: you send recruiter intent as natural-language qualification statements; Teamcast maps them internally to skills, generates the interview plan, conducts the session, and delivers a structured assessment back via webhooks.

Base URL	Auth	Format
https://mayaapi.teamcast.ai/api/v1/integration	X-API-Key + X-Tenant-ID headers	application/json

Webhook URL is registered once per tenant in your account settings — not passed per-request. Set autoApprovePlans: true in your tenant config to skip the manual plan approval gate.

Guides

REST Endpoints

Full endpoint reference with request and response schemas.

HITL Workflow

Human-in-the-loop approval gates for plan review and assessment verdicts.

Webhooks

HMAC-signed event notifications with retry policy and payload schemas.

Privacy & Data

Retention windows, PII purge API, and data controller/processor boundaries.

Complete Workflow

A typical integration flows from interview creation to candidate link delivery:

text

Your System                        AI Interview System
      |                                    |
      |-- POST /integration/interviews --->|  (qualifications[], candidateRef)
      |                                    |-- Validate data
      |                                    |
      |   IF data is complete:             |
      |<-- 201 { state: VALIDATING } ------|
      |<-- webhook: plan_generated --------|  (plan ready)
      |                                    |
      |   IF data is incomplete:           |
      |<-- 201 { state: INFO_NEEDED } -----|
      |<-- webhook: info_needed ----------|
      |                                    |
      |   [Supply missing fields]          |
      |-- PATCH .../info ----------------->|
      |<-- webhook: info_completed --------|
      |<-- webhook: plan_generated --------|
      |                                    |
      |   [Recruiter reviews plan]         |
      |   OR autoApprovePlans=true ------->|  (no manual step)
      |-- POST .../plan/approve ---------->|
      |<-- 200 { interviewLink: ... } -----|
      |<-- webhook: interview.approved ----|

Endpoints at a Glance

Method	Endpoint	Description
POST	/integration/interviews	Submit an interview request
GET	/integration/interviews/:runId	Get current status, plan, and assessment
DELETE	/integration/interviews/:runId	Cancel an interview
PATCH	/integration/interviews/:runId/info	Supply missing data (state: INFO_NEEDED)
POST	/integration/interviews/:runId/plan/approve	Approve the AI-generated plan
POST	/integration/interviews/:runId/plan/reject	Reject the plan with feedback
PATCH	/integration/interviews/:runId/plan/revise	Request targeted revisions
POST	/integration/interviews/:runId/assessment/approve	Approve the AI assessment
POST	/integration/interviews/:runId/assessment/reject	Reject the assessment
POST	/integration/interviews/:runId/assessment/chat	Ask questions about an assessment
DELETE	/integration/interviews/:runId/candidate-data	Purge candidate PII from a record
GET	/integration/rankings	Candidate rankings by assessment score

Quick Start — Qualification-First

bash

# Submit an interview using qualification statements — no PII required
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",
    "position": "Senior Software Engineer",
    "level": "SENIOR",
    "qualifications": [
      "5+ years production TypeScript experience",
      "Demonstrated distributed systems design",
      "Strong async/concurrency patterns knowledge"
    ],
    "companyName": "Acme Corp"
  }'

Response 201

{
  "runId": "run_1749123456_a1b2c3d4",
  "interviewId": "interview-uuid",
  "state": "VALIDATING_SKILLS",
  "message": "Interview request accepted. Skill validation in progress.",
  "dataQuality": "EXCELLENT"
}

Workflow States

State	Description
RECEIVED	Request received, data validation running
INFO_NEEDED	Critical data is missing — supply via PATCH .../info
VALIDATING_SKILLS	Qualifications validated, plan generation started
GENERATING_PLAN	Plan regenerating (after revision request)
PENDING	Plan ready — awaiting recruiter approval (skipped if autoApprovePlans)
APPROVED	Plan approved, candidate interview link generated
REJECTED	Plan rejected by recruiter
SCHEDULED	Interview scheduled
IN_PROGRESS	Interview currently running
COMPLETED	Interview complete, assessment available
ASSESSMENT_PENDING	Awaiting recruiter assessment verdict
ASSESSMENT_APPROVED	Assessment approved
CANCELLED	Interview cancelled

Webhook notifications are sent to the URL registered in your tenant settings. See the Webhooks guide for event schemas and HMAC signature verification.

Was this page helpful?

Previous← Postman Collections

NextREST Endpoints →