---
title: "Match Preview"
method: POST
path: "/api/job-roles/match-preview"
tags: ["Job Roles"]
---

# Match Preview

`POST /api/job-roles/match-preview`

## 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/job-roles/match-preview`
- Auth: HTTP bearer

Score a single résumé against 1-5 active job roles in parallel.
Stateless preview — no candidate is created. The recruiter sees a
ranked table and then commits one (or more) of the results via the
existing add-candidate-to-role endpoint.

Built for the agency flow where one résumé might fit Tesco Sr SE,
Walmart Sr SE, and Stripe Sr SE simultaneously and the recruiter
wants the comparison before picking where to send the screening
invite. In-house TAs benefit too — match one résumé against several
of their own open positions without re-uploading.

Cap of 5 roles per request bounds latency (~5s) and LLM spend
per click. Match results land in the existing match_results cache
(compute_match handles dedup by sha256(jd + résumé)), so resubmitting
the same résumé + selection costs nothing.

## Response `200`

Successful Response

- MatchPreviewResponse
  - `extracted_name` string, nullable, required
  - `extracted_email` string, nullable, required
  - `resume_text_preview` string, required
  - `results` MatchPreviewResultItem[], required
    - `job_role_id` string, required
    - `role_title` string, required
    - `hiring_company_display` string, nullable, required
    - `score` integer, nullable, required
    - `recommendation` string, nullable, required
    - `summary` string, nullable, required
    - `requirements_met` integer, nullable, required
    - `requirements_total` integer, nullable, required
    - `strengths` string[], required
    - `concerns` string[], required
    - `suggested_questions` string[], required
    - `cached` boolean, required
    - `error` string, nullable, required

## 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)