---
title: "Match resumes against a job description"
method: POST
path: "/api/public/v1/match"
tags: ["Public API v1 — Resume Matching", "Public API v1 — Resume Matching"]
---

# Match resumes against a job description

`POST /api/public/v1/match`

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

Match up to 10 resumes against a job description. Returns ranked candidates with fit scores, requirements checklist, strengths, concerns, and suggested Round 1 interview questions.

Results are cached — same resume + JD won't re-run analysis.

Use the returned match_id to screen or schedule top candidates.

## Request body

- MatchRequest
  - `role` string, required: Job title.
  - `job_description` string, required: Full job description text.
  - `resumes` ResumeInput[], required: 1-10 resumes to match.
    - `resume_text` string, required: Resume as plain text.
    - `candidate_name` string, nullable: Optional — auto-extracted from resume if not provided.
    - `candidate_email` string, nullable: Optional — auto-extracted from resume if not provided.

## Response `200`

Successful Response

- MatchResponse
  - `role` string, required
  - `candidates_matched` integer, required
  - `ranking` MatchResultItem[], required
    - `rank` integer, required
    - `match_id` string, required
    - `candidate_name` string, required
    - `candidate_email` string, nullable, required
    - `overall_score` integer, required
    - `recommendation` string, required
    - `summary` string, required
    - `requirements_met` integer, required
    - `requirements_total` integer, required
    - `strengths` string[], required
    - `concerns` string[], required
    - `suggested_questions` SuggestedQuestion[], required
      - `question` string, nullable
      - `rationale` string, nullable
    - `cached` boolean, 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)