Public API v1
Public API v1

Get interview status, scorecard, and transcript

Retrieve the full interview analysis including scorecard with competency scores, timestamped evidence, action plan, communication metrics, and transcript. Evidence items include timestamps — use with recording_url for audio playback. The scorecard covers every interview kind: AI screenings, AI interviews and submitted recordings. Competencies the interview never reached are omitted from competencies and listed in not_assessed; coverage_summary, score_confidence and transcript_quality say how much of the rubric the score rests on. A completed interview with scorecard: null carries a top-level transcript_quality whose label ('partial' or 'invalid') says the candidate said too little to score, with the word count the gate measured.

get/api/public/v1/interviews/{interview_id}

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}
  • Auth: HTTP bearer

Path parameters

interview_idstring required

Response

Successful Response

idstring required

Unique interview ID.

statusstring required

'pending', 'processing', 'completed', 'failed'.

transcript_statusstring required

Transcription sub-status.

analysis_statusstring required

Analysis sub-status.

input_modestring required

'meeting' or 'recording'.

created_atstring required

ISO 8601 timestamp.

rolestring required

Job role.

recording_urlstring nullable

URL of the interview recording. Use with evidence timestamps for playback.

metadataobject nullable

Custom metadata from submission.

errorstring nullable

Error message if failed.

failure_reasonstring nullable

Why the interview ended without a call, when it did. 'never_joined': nobody started it within its join window; 'cancelled_by_integrator': you cancelled it before it started. Both mean nothing was charged and nothing went wrong — read them as 'did not happen', not as a failure. Other values describe a meeting bot or processing failure. Null otherwise.

joinableboolean nullable

For interviews the candidate joins by link: true while the link can still be started. False once started or finished, once cancelled, or once its join window passed. Null for meeting and recording interviews. Reuse the link while true; start a new interview when false.

join_expires_atstring nullable

For interviews created through this API: when the link stops working if nobody has started it — one hour after scheduled_at, or after creation when unbooked. Null when no window applies.

Example response

{
  "scorecard": {
    "overall_score": 78,
    "recommendation": "hire",
    "competencies": [
      {
        "name": "Team Leadership",
        "score": 90,
        "assessment": "Excellent",
        "coverage": "covered"
      }
    ],
    "action_plan": [
      {
        "priority": "critical",
        "title": "Address Technical Roadmap Execution Gap",
        "deadline": "Within 48 hours"
      }
    ],
    "communication": {
      "fluency": 63,
      "fillers_per_min": 1.6,
      "avg_pause_seconds": 7.4,
      "words_per_minute": 152,
      "duration_seconds": 438,
      "word_count": 1109,
      "rating": "excellent",
      "filler_words": [
        {
          "word": "uh",
          "count": 2
        }
      ]
    },
    "not_assessed": [
      "Talent Development",
      "Strategic Communication"
    ],
    "score_confidence": "medium",
    "calibrated_for_level": "entry",
    "transcript_quality": "full",
    "band": "Good"
  },
  "transcript": {
    "segments": [
      {
        "speaker": "candidate",
        "start_seconds": 12.5,
        "end_seconds": 18.3
      }
    ]
  },
  "transcript_quality": {
    "label": "invalid"
  }
}

Changes

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