This page is the implementation contract for POST /api/v1/candidates/match. Use it when building clients, validating payloads, and debugging integration issues.

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

Request schema

MatchRequest

Field	Type	Required	Default	Constraints	Notes
job_description	string	Yes	—	min 20, max 50000 chars	Primary role brief used for matching.
top_n	integer	No	10	1..50	How many candidates to return.
similarity_threshold	number	No	0.5	0.0..1.0	Minimum score to include in results.
filters	object \| null	No	null	—	Optional hard constraints (skills/languages/location).
include_reasoning	boolean	No	true	—	Attempts to include reasoning text where available.

Filters object

Supported filter keys are skills, languages, country, and city. Unknown fields are rejected.

Request examples

curl -X POST "$BASE_URL/api/v1/candidates/match" \
  -H "Authorization: Bearer vtk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "job_description": "Senior Data Engineer with Python and AWS",
    "top_n": 5
  }'

Response schema

MatchResponse

Field	Type	Required	Default	Constraints	Notes
matches	MatchCandidate[]	Yes	—	—	Ranked result list, may be empty.
total_candidates_searched	integer	Yes	—	—	Candidates evaluated before final threshold filtering.
total_above_threshold	integer	Yes	—	—	Candidates meeting threshold before top_n truncation.
embedding_model	string	Yes	—	—	Embedding model used for similarity scoring.

Important match fields

candidate_id and candidate_url for deep links
similarity_score as baseline rank metric
match_score and reasoning when reranking is available
profile_links[] for profile-specific context

Common bad requests and fixes

job_description too short

Ensure at least 20 characters with meaningful role requirements.

top_n out of range

Use values between 1 and 50 only.

Unknown fields included

This endpoint rejects extra fields. Remove typos and unsupported keys from payloads.

Validation behavior

Request objects are strict. Treat 422 as a schema contract violation and fix payload generation before retrying.