---
title: "Compare candidates side by side"
method: POST
path: "/api/public/v1/compare"
tags: ["Public API v1 — Comparison", "Public API v1 — Comparison"]
---

# Compare candidates side by side

`POST /api/public/v1/compare`

## 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/compare`
- Auth: HTTP bearer

Compare 2-4 candidates with overall ranking, competency matrix, head-to-head on overlapping rounds, communication comparison, and risk assessment. Handles candidates at different interview stages with confidence flags and warnings.

## Request body

- CompareRequest: Compare 2-3 candidates side by side.
  - `candidate_ids` string[], required: List of 2-4 candidate IDs to compare. All must belong to your organization.

## Response `200`

Successful Response

- CompareResponse: Side-by-side candidate comparison with ranking, competency matrix, and head-to-head.
  - `role` string, nullable: Primary role being compared.
  - `candidates_compared` integer, required: Number of candidates in comparison.
  - `ranking` CandidateRanking[], required: Candidates ranked by overall score (highest first).
    - `rank` integer, required: Rank position (1 = highest score).
    - `candidate_id` string, required: Candidate ID.
    - `name` string, required: Candidate name.
    - `overall_score` integer, required: Overall score 0-100.
    - `recommendation` string, required: strong_hire | hire | maybe | no_hire
    - `confidence` string, required: high | medium | low
    - `rounds_completed` integer, required: Number of interview rounds completed.
    - `top_strengths` string[]
    - `key_concerns` string[]
  - `competency_matrix` CompetencyMatrixEntry[]: Each competency with per-candidate scores. 'best' marks the winner.
    - `competency` string, required: Competency name.
    - `scores` object, required: Candidate ID → score (0-10). Null if not assessed.
    - `best` string, nullable: Candidate ID with highest score.
  - `head_to_head` HeadToHead, required
    - `overlapping_rounds` string[]: Round names all candidates have completed.
    - `per_round` HeadToHeadRound[]
      - `round` string, required: Round name.
      - `scores` object, required: Candidate ID → {score, recommendation}
  - `communication` CommunicationEntry[]: Communication metrics per candidate.
    - `candidate_id` string, required
    - `name` string, required
    - `fluency` number, nullable
    - `wpm` number, nullable
    - `fillers_per_min` number, nullable
    - `trend` string: improving | stable | declining | unknown
  - `risk_comparison` RiskEntry[]: Risk level per candidate.
    - `candidate_id` string, required
    - `name` string, required
    - `risk_level` string, required: low | medium | high | unknown
    - `confidence` string, required
  - `warnings` string[]: Warnings about comparison fairness (e.g., different round counts).
  - `ai_summary` string, nullable: AI-generated comparison narrative.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/thebetterhire/apis/interanalysis-b2b-api.md) · [All operations](https://skmtc.dev/thebetterhire/apis/interanalysis-b2b-api/llms.txt) · [OpenAPI document](https://skmtc.dev/thebetterhire/apis/interanalysis-b2b-api/revisions/c8ad03e900ea?raw)