Public API v1 — Candidate Feedback
Public API v1 — Candidate Feedback

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.

post/api/public/v1/interviews/{interview_id}/candidate-feedback

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

interview_idstring required

Request body

self_readstring nullable

The candidate's own read of how it went, written before seeing any result. When present, the feedback's heard sets what the interviewer actually heard against it.

regenerateboolean

Discard the stored feedback and generate again. Billed again. Without it a second call returns the stored object for free.

asyncboolean

Answer 202 at once and generate in the background, instead of holding the request open for the generation (typically 20-60 seconds). When it is done, the candidate_feedback.completed webhook fires; or poll GET (409 FEEDBACK_IN_PROGRESS while it runs). A stored result, the sandbox and every error still answer at once.

Example request

{
  "self_read": "I think the system design part went well but I rambled on pricing."
}

Response

Successful Response

interview_idstring required
status'ready' | 'unavailable' required
generated_atstring nullable
unavailable_reason'not_scored' | 'generation_failed' nullable
contract_versionstring
scorecard_fingerprintstring nullable

Changes

No recorded changes to this operation across all 1 revision of this API.