Back to Docs
Developer Docs

Candidate Matching Overview

Understand how Vitae candidate matching works, when to use it, and the core endpoint used by agent workflows.

Candidate matching compares a job description against your organisation's candidate data and returns a ranked shortlist. This is the core endpoint used by agent skills and recruiter automation flows.

Endpoint contract

POST/api/v1/candidates/match
Authentication
Bearer JWT or Bearer vtk_ API key
Plan requirement
Professional+
Rate limits
10/min, Pro 30/day, Enterprise 500/day

How matching works

  1. Your system sends a role brief in job_description.
  2. Optional filters constrain candidate search space.
  3. Candidates are ranked by similarity to role requirements.
  4. Response returns ranked matches and metadata for observability.

What you get in a response

  • matches[] with candidate identity, score data, and links
  • total_candidates_searched and total_above_threshold
  • embedding_model for diagnostics and reproducibility

Understanding scoring fields

similarity_score is the base score from embedding similarity. In some cases, a second score (match_score) and reasoning may be included when reranking is enabled and available.

When matches are empty

Empty matches with HTTP 200 is valid. It usually indicates strict filters, high similarity threshold, or weak role/candidate overlap.

Noob tip

Start without filters and use a moderate threshold. Add filters only after confirming your baseline matching quality.
  • Matching Request & Response
  • Candidate Matching Filters
  • Matching Errors & Limits