API Reference
Interviews
The interview run resource — fields, states, and the two response shapes every endpoint returns.
An interview run is created from a role (position, level, skills or job description) plus a candidate identifier. It flows through a single state machine regardless of whether you drive it via the REST Integration API or the JSON-RPC surface.
Run states
| State | Meaning |
|---|---|
INFO_NEEDED | Missing required fields — see missing_fields |
VALIDATING | Automated data validation running |
GENERATING_PLAN | Interview plan being generated |
PENDING | Plan awaiting human approval |
APPROVED | Plan approved, invite not yet sent |
INVITED | Candidate invited to the interview |
IN_PROGRESS | Live interview underway |
ASSESSMENT_PENDING | Assessment generated, awaiting human approval |
ASSESSMENT_READY | Assessment approved and delivered |
COMPLETED | Terminal — run finished |
REJECTED | Terminal — plan or assessment rejected |
CANCELLED | Terminal — cancelled by caller |
Creation payload
At least one candidate identifier (candidate_ref, candidate_name, or candidate_email) and one skills source (skills[], qualifications[], or job_description) are required.
InterviewCreateParams
{
external_id: string; // partner idempotency key, scoped per tenant
candidate_ref?: string; // opaque partner-side id — use instead of PII where possible
candidate_name?: string;
candidate_email?: string;
position: string;
level: "ENTRY" | "MID" | "SENIOR" | "LEAD" | "EXEC";
skills?: string[];
qualifications?: string[]; // free-text qualification statements
job_description?: string;
company_name?: string;
company_description?: string;
candidate_resume?: string;
candidate_profile_url?: string;
duration_minutes?: number; // 15–120
callback_url?: string; // per-run webhook override
}Response shapes
POST /integration/interviews (and interview.create) return RunAccepted:
RunAccepted
{
run_id: string; // run_<epoch>_<hex>
interview_id: string;
state: A2ARunState;
message: string;
missing_fields?: MissingField[]; // present when state === "INFO_NEEDED"
}GET /integration/interviews/:runId (and interview.status) return InterviewStatusResult:
InterviewStatusResult
{
run_id: string;
interview_id: string;
state: A2ARunState;
awaiting_human: boolean;
missing_fields?: MissingField[];
interview_link?: string;
coverage_summary?: {
overall_coverage: "sufficient" | "partial" | "insufficient";
gap_competencies: string[];
covered_count: number;
total_count: number;
};
recording?: { chunks: string[]; expires_at: string }; // signed, expiring URLs
}coverage_summary is the only assessment signal ever returned — there is no score field and no hire/no-hire recommendation anywhere in this response. See Privacy & Data.Was this page helpful?