Candidate Comparison — compare two resumes by job title

Candidate Comparison API

What it does

Candidate Comparison compares two resumes against a job title and returns a structured head-to-head assessment. Send resumeA, resumeB, and jobTitle, and get back a winner, a short rationale, and a comparisonMatrix covering experience, softSkills, and technicalSkills.

Use it when you need a fast first-pass screen before a recruiter or hiring manager reviews the full packet. It helps you turn unstructured resumes into a consistent comparison for the same role, which is useful for shortlist ranking, interview triage, or building an internal hiring workflow that needs a clear recommendation.

The response is simple to consume: one candidate is identified as the winner, with supporting text for why they were chosen. The comparison matrix breaks the decision into specific dimensions so you can show the basis for the result in your own UI or audit trail.

Candidate Comparison is designed for resume-to-role evaluation, not general document parsing. If your workflow starts with two candidate resumes and a target position, this endpoint gives you a direct, machine-readable comparison.

Quickstart

Compare two candidates against a job title by sending their resumes in one JSON request.

curl -X POST "http://localhost:8080/namastesumalya/compare-two-candidates-head-to-head" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "resumeA": "Resume content of candidate A...",
    "resumeB": "Resume content of candidate B...",
    "jobTitle": "Senior Software Engineer"
  }'

What you'll get back

Returns a JSON object with optional top-level fields: winner and rationale are strings, and comparisonMatrix is an object. When present, comparisonMatrix can include experience, softSkills, and technicalSkills, each as a string.

{
  "winner": "B",
  "rationale": "Candidate B's alignment with modern cloud-native practices makes them a better fit for our future-state architecture.",
  "comparisonMatrix": {
    "experience": "A has deeper tenure (15y vs 8y), but B has more relevant modern stack experience.",
    "softSkills": "Both demonstrate strong leadership, but B shows better alignment with modern agile engineering cultures.",
    "technicalSkills": "A is legacy-enterprise focused; B is cloud-native and high-performance focused."
  }
}

About this endpoint

What it does

Compares two candidate resumes against a job title and returns a winner, a rationale, and a comparison matrix of key dimensions.

Request Body

Parameter	Type	Mandatory	Description
resumeA	String	Yes	Resume content for candidate A.
resumeB	String	Yes	Resume content for candidate B.
jobTitle	String	Yes	The job title used as the comparison context.

Response

Returns a JSON object with three top-level fields: winner and rationale are strings, and comparisonMatrix is an object containing string fields for experience, softSkills, and technicalSkills.

Parameter	Type	Mandatory	Description
winner	String	No	The selected candidate identifier.
rationale	String	No	Explanation for why that candidate was chosen.
comparisonMatrix	Object	No	Comparison details across key dimensions. Contains `experience`, `softSkills`, and `technicalSkills` as string fields.

Body

Name

Type

Description

bodyREQUIRED

object

—

Quickstart

What you'll get back

About this endpoint

What it does

Request Body

Response

Body

Errors any endpoint can return