Score one candidate against one role

POST /match

Calibrated 0-100 fit score with band, structured explanation (met/missed requirements with evidence), and signals. Hard requirements dominate: high text similarity cannot rescue missing must-haves, and large experience shortfalls cap the score.

Provide the candidate as parsed candidate JSON or raw resume_text/resume_url/resume_file (parsed inline, +1 credit). Same for the role via role or jd_text/jd_url/jd_file.

Scoring always runs on the bias-redacted feature set; fairness.scored_on_redacted_input is always true. Results are evidence for human decisions — never hire/reject verdicts.

Cost: 2 credits + 1 per inline parse.

Request body

Field	Type	Description
`candidate`	object	Normalized candidate (résumé) JSON. Dates render as YYYY-MM when the month is known, YYYY otherwise. Rezmatch.ai never stores this — it exists only in the response.
`resume_text`	string
`resume_url`	string
`resume_file`	string
`role`	object	Normalized role (job description) JSON.
`jd_text`	string
`jd_url`	string
`jd_file`	string
`explain`	boolean	Include the prose notes

Example request


curl -X POST "https://api.rezmatch.ai/match" \
  -H "x-access-key: $TALENTKIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "resume_text": "Jane Doe. Senior Backend Engineer at Foo since 2019. Skills: Go, Kubernetes, PostgreSQL.",
  "jd_url": "https://job-boards.greenhouse.io/acme/jobs/123456"
}'

Example response


{
  "success": true,
  "data": {
    "score": 84,
    "band": "strong",
    "explanation": {
      "met": [
        {
          "requirement": "Go (3+ years)",
          "evidence": "Go",
          "verified": true
        }
      ],
      "missed": [
        {
          "requirement": "Apache Kafka",
          "severity": "nice_to_have"
        }
      ],
      "over_qualified": false,
      "under_qualified": false,
      "seniority_fit": "match",
      "notes": "The candidate meets all must-have requirements with strong skill similarity and a matching seniority level. The nice-to-have Kafka requirement was not evidenced."
    },
    "signals": {
      "must_have_coverage": 1,
      "nice_to_have_coverage": 0,
      "skill_similarity": 0.8408,
      "seniority_gap": 0
    },
    "fairness": {
      "scored_on_redacted_input": true
    }
  },
  "credits_used": 4,
  "request_id": "req_ef6f1151-81c7-47a8-8086-88de98682bcd"
}

Errors

Status	Meaning
`401`	invalid_key — missing, unknown, or revoked access key
`402`	insufficient_credits — top up in the dashboard; the failed call is not charged
`422`	Inputs incomplete (`missing_candidate` / `missing_role`) or extraction failed (`parse_failed`)

All errors share the error envelope.

Try it

Open this endpoint in the interactive playground — requests run with your API key.