Vitae helps recruitment teams turn job descriptions into ranked candidate shortlists. If you are integrating for the first time, this guide gets you from zero to first successful API call in under 10 minutes using POST /api/v1/candidates/match.

Endpoint contract

POST/api/v1/candidates/match

Authentication: Bearer JWT or Bearer vtk_ API key
Plan requirement: Professional or Enterprise
Rate limits: 10/min, Pro 30/day, Enterprise 500/day

What you will build in 5 minutes

By the end of this page, you will send a real job description to Vitae and receive a structured shortlist of matched candidates with URLs your recruiters can open directly.

Prerequisites

Setup checklist

You have a Professional or Enterprise account
You have a valid bearer token (JWT or vtk_ API key)
You know your API base URL (for local, staging, or production)
Your organisation has candidate records to search

Your first API call

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, AWS, and ETL ownership",
    "top_n": 5
  }'

How to confirm it worked

HTTP status is 200
Response has matches array (can be empty and still valid)
Response includes metadata like total_candidates_searched

Most common first-time errors

401 Unauthorized

Your bearer token is missing, expired, or malformed.

403 Forbidden

Your account tier does not allow matching endpoint access.

422 Unprocessable Entity

Request payload violates schema constraints (for example, job description shorter than 20 characters).

Noob tip

Start with the smallest valid payload first. After you confirm auth and response parsing, then add filters and advanced parameters.

Next steps

Read Authentication & API Keys to pick JWT vs API key strategy
Read Matching Request & Response for full schema details
Read Matching Errors & Limits before production rollout