Generate candidate-facing feedback for a completed interview
Turns the interview's scorecard into feedback written for the candidate: the one gap to the next level, the habit that cost the most (with a pointer to the moment), the best moment (with a pointer), one line per competency, and, when self_read is given, what the interviewer actually heard.
From contract 2.0, feedback.structure lists the candidate's stories (a main question plus the interviewer's follow-ups): each framework part present, when_asked (given only after the interviewer asked) or missing, with ref.first_turn / ref.last_turn indexing transcript.segments[] on GET /interviews/{id}. structure.status is ready, not_applicable (skill rounds) or unavailable (the rest of the feedback still stands). From 2.1, structure.openings reads the introduction and the "why this role" answer: seconds_spoken (the candidate's own turns) and focus (on_role, partly or wandered), with a note.
Every pointer is {competency, evidence}: the competency name and an index into that competency's evidence[] on GET /interviews/{id}, so you can play the seconds behind it. No numbers ever appear in the text.
Works for every completed interview kind. Generated once and stored: a second call returns the same object without a charge unless regenerate: true. status: unavailable with unavailable_reason is a normal, unbilled answer (not_scored when the transcript-quality gate stripped scoring, generation_failed after three rejected attempts). 409 FEEDBACK_IN_PROGRESS with Retry-After while another request is generating feedback for the same interview.
With "async": true, 202 {status: "generating"} instead of waiting; the candidate_feedback.completed webhook (data.status, data.structure_status) fires when it is stored, and GET returns it.
Billed once per generation as the feedback action, above the per-candidate cap.
Request
- Base URL: https://api.thebetterhire.ai (the document declares no server; this is the origin it was published from)
- URL: https://api.thebetterhire.ai/api/public/v1/interviews/{interview_id}/candidate-feedback
- Auth: HTTP bearer
Path parameters
Request body
Example request
{
"self_read": "I think the system design part went well but I rambled on pricing."
}Response
Successful Response
Changes
No recorded changes to this operation across all 1 revision of this API.