Integration API (A2A)
Human-in-the-loop workflow
Two approval gates keep a person in control of what the AI produces before it moves forward.
Rather than letting the AI silently drive a candidate through an interview process, every run stops at two checkpoints. Each gate can be driven by your integration (approve/reject/revise via the API) or by a recruiter in the Teamcast dashboard — whichever acts first wins.
Gate 1 — Plan approval
After interview.create, Teamcast generates an interview plan (question areas, target duration, seniority-calibrated depth) from the role and candidate data. The run sits in PENDING until a decision is made:
| Decision | Effect |
|---|---|
| Approve | Run moves to APPROVED → INVITED; the candidate receives an interview link |
| Reject | Run moves to the terminal REJECTED state |
| Revise | Comments are fed back in and a new plan is generated for another round of review |
Gate 2 — Assessment approval
After the candidate completes the live interview, Teamcast's deterministic scoring pipeline (no LLM in the scoring path — see Architecture) produces a coverage-only assessment. The run sits in ASSESSMENT_PENDING until approved or rejected:
| Decision | Effect |
|---|---|
| Approve | Run moves to ASSESSMENT_READY/COMPLETED and interview.assessment_ready fires |
| Reject | Run moves to the terminal REJECTED state — no assessment is delivered |
Auto-approve
A tenant can configure auto-approve for either gate (via tenant webhook/workflow settings) to run fully hands-off once you trust the plan-generation and scoring pipeline for a given role family. Both gates remain independently controllable — you can auto-approve plans while still requiring a human on every assessment, for example.
INFO_NEEDED — before either gate
If required candidate or role data is missing at creation time, the run short-circuits into INFO_NEEDED instead of failing. Each missing field carries a severity (required blocks planning; recommended doesn't) and a ready-to-use follow-up question, so you can either prompt the recruiter/candidate directly or relay it verbatim in your own UI. Submit answers with interview.complete-info / PATCH .../info.
/integration/interviews/:runId/plan/* / /assessment/* endpoints or the interview.approve / assessment.approve JSON-RPC methods.