Home · Use cases · Jobs · Score a candidate against a role you describe

Score a candidate against a role you describe

For: hiring and recruiting-operations teams who rank people for a role and want the reason for each score. One run is 2 calls and 60 credits.

Get an API key   Run a step free

The job

A shortlist needs an order and a reason. Reading each profile against a job description by hand takes long, and two people read the same profile differently.

Web data or web intelligence?

Raw pages leave the comparing to you. Structured answers score a person against the role you wrote, with the score broken down, an evaluation of fit and the job it used, and then set two or more people side by side on named dimensions with key insights.

The calls, in order

StepCallWhat it gives youCreditsDocs
1POST /v1/candidate_evaluateone person against your role: a score with its breakdown and an evaluation of fit50Fields
2POST /v1/compare_peopletwo or more people side by side: dimensions, key insights and a summary10Fields

What one run costs

fact The credits per call are the catalog's: 50 + 10 = 60 per run, so 60,000 credits per 1,000 runs. calculated At the plan prices on the pricing page that is about $478 per 1,000 runs on Production and $588 on Builder (plan price divided by its monthly credits, times the credits). The Free plan gives 100 credits a month with no card.Formula

Your runs a month

Real responses, step by step

fact Captured from https://api.foxapis.com on 19 November 2026 with the documented sample input of each call; every value below is from that response, shortened where long. The nightly check on the status page lists each of these calls as working.

Step 1: POST /v1/candidate_evaluate

The input: {"candidateName":"Patrick Collison","company":"Stripe","jobDescription":"Chief executive of a payments company"}. A real response had these fields.

FieldValue in that response
joban object with 2 fields
successtrue
version1.3
foxscore87
candidatean object with 3 fields
evaluationan object with 14 fields
curl -X POST 'https://api.foxapis.com/v1/candidate_evaluate' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"candidateName":"Patrick Collison","company":"Stripe","jobDescription":"Chief executive of a payments company"}'

Step 2: POST /v1/compare_people

The input: {"subjects":[{"name":"Patrick Collison","company":"Stripe"},{"name":"John Collison","company":"Stripe"}]}. A real response had these fields.

FieldValue in that response
successtrue
comparisonsa list of 1
version3
peoplea list of 2
dimensionsa list of 30
key_insightsa list of 5
curl -X POST 'https://api.foxapis.com/v1/compare_people' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subjects":[{"name":"Patrick Collison","company":"Stripe"},{"name":"John Collison","company":"Stripe"}]}'

All of it as one script

The same 2 calls chained, with a key placeholder. Swap the inputs for your own.

// 2 calls, one job run. Put your key in YOUR_API_KEY.
const KEY = "YOUR_API_KEY", BASE = "https://api.foxapis.com";
async function call(method, path, input) {
  const url = BASE + path + (method === "GET" ? "?" + new URLSearchParams(input) : "");
  const r = await fetch(url, { method, headers: { Authorization: "Bearer " + KEY, "Content-Type": "application/json" }, body: method === "GET" ? undefined : JSON.stringify(input) });
  if (!r.ok) throw new Error(path + " answered " + r.status);
  return r.json();
}
const step1 = await call("POST", "/v1/candidate_evaluate", {"candidateName":"Patrick Collison","company":"Stripe","jobDescription":"Chief executive of a payments company"});   // one person against your role: a score with its breakdown and an evaluation of fit
const step2 = await call("POST", "/v1/compare_people", {"subjects":[{"name":"Patrick Collison","company":"Stripe"},{"name":"John Collison","company":"Stripe"}]});   // two or more people side by side: dimensions, key insights and a summary
console.log({ step1, step2 });

What you could build

Limits, plainly

The score depends on the job description you send and on what public sources say about the person; it is a research aid, not a hiring decision. One person per evaluation call. Both calls answer after a short wait. Tested on one well-known person on 19 November 2026.

Field lists and the rest of each data type: Every people and company research field. Single calls with code in six languages: task APIs.

Other jobs: Track a product's open-source and launch momentum · Build a crypto and DeFi dashboard · Write a biomedical research brief · Analyse players and games for a gaming community · Watch artists for a label or a playlist curator · Give an AI agent structured answers instead of raw pages · Enrich a lead list with company and developer signals · Check a UK company and who controls it · Compare your app with a rival's on both phone stores · Profile a creator before a sponsorship · Check an open-source model and its repository before you adopt it · Profile a developer expert before you hire or sponsor · Check a person's claims before you hire or partner · Prepare a sales brief on a company and score a prospect's message · Check how AI assistants show your domain · Research an investor before you pitch.

Source: live calls to https://api.foxapis.com on 19 November 2026. Values reflect that moment and those inputs. Credits per call are the catalog's.

How we calculate

Data: the FoxAPIs catalog and plans, read 19 November 2026. Every other figure on this page is copied from the record, not calculated by us.

Run this free, then pay per call

Free to start: 100 credits, no card. Then from $10. Credits you buy never expire. Use them at your own pace. Get my free key

One call costs 1 credit. That is $7.96 per 1,000 calls on the Production plan and $9.80 on Builder (plan price divided by its monthly credits). The Free plan gives 100 credits a month with no card.

Run this freeBuy credits

Building an AI agent?

See the MCP server