Candidate Comparison — compare resumes by job fit

Candidate Comparison API

What it does

Candidate Comparison lets you compare two resumes against a job title and get a structured head-to-head result. Send resumeA, resumeB, and jobTitle, and the API returns a winner, a short rationale, and a comparisonMatrix with separate notes for experience, softSkills, and technicalSkills.

Use it when you need a fast screening layer for hiring workflows, shortlist generation, or internal review tools. It helps you turn unstructured resume text into a consistent comparison that recruiters, hiring managers, or matching systems can read quickly.

The response is explicit: one candidate is selected as the winner, and the comparison matrix explains the tradeoffs behind that decision. That makes it easier to surface why one resume is a better fit for a role, rather than relying on a single score with no context.

If you are building an ATS, recruiting assistant, or candidate triage flow, Candidate Comparison gives you a simple API for pairwise resume evaluation without having to parse the reasoning yourself.

curl -X POST "https://api.eu.apyverse.com/namastesumalya/compare-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" }'

{ "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 each other, with an optional job title context, and returns a winner plus a written rationale. The response also includes a comparison matrix with breakdowns for experience, soft skills, and technical skills.

Request Body

Parameter	Type	Mandatory	Description
resumeA	String	Yes	Resume content of candidate A.
resumeB	String	Yes	Resume content of candidate B.
jobTitle	String	No	Job title context for the comparison.

Response

Returns a JSON object with winner and rationale string fields, plus a comparisonMatrix object containing experience, softSkills, and technicalSkills string fields.

Parameter	Type	Mandatory	Description
winner	String	No	The selected winner of the head-to-head comparison.
rationale	String	No	Explanation for why that candidate was chosen.
comparisonMatrix	Object	No	Comparison details broken down by experience, soft skills, and technical skills.
comparisonMatrix.experience	String	No	Summary of how the candidates compare on experience.
comparisonMatrix.softSkills	String	No	Summary of how the candidates compare on soft skills.
comparisonMatrix.technicalSkills	String	No	Summary of how the candidates compare on technical skills.

Body

Name

Type

Description

bodyREQUIRED

object

—

Candidate Comparison API

What it does

QUICKSTART

Quickstart

What you'll get back

About this endpoint

What it does

Request Body

Response

Body

Errors any endpoint can return