Process one or more candidate resumes against a job description. This endpoint analyzes the candidate's qualifications and provides a detailed assessment of their fit for the role.
Endpoint
Authentication
X-API-Key: your_api_key_here
Request Format
{
"job": {
"title": "Senior Software Engineer",
"description": "Full job description text...",
"external_id": "your-job-reference-id",
"company": "Your Company Name"
},
"candidates": [
{
"name": "Candidate Name",
"email": "candidate@example.com",
"resume_text": "Full resume text...",
"external_id": "your-candidate-reference-id"
}
],
"processing_options": {
"mode": "async" // or "sync"
}
}
Parameters
| Parameter |
Type |
Required |
Description |
| job.title |
string |
Yes |
Title of the job position |
| job.description |
string |
Yes |
Full text of the job description |
| job.external_id |
string |
Yes |
Your unique reference ID for this job |
| job.company |
string |
Yes |
Company name offering the position |
| candidates |
array |
Yes |
Array of candidate objects to evaluate |
| candidates[].name |
string |
Yes |
Candidate's full name |
| candidates[].email |
string |
Yes |
Candidate's email address |
| candidates[].resume_text |
string |
Yes |
Full text of the candidate's resume |
| candidates[].external_id |
string |
Yes |
Your unique reference ID for this candidate |
| processing_options.mode |
string |
No |
Processing mode: "async" (default) or "sync" |
Processing Modes: The API supports two processing modes:
- async (recommended): Returns immediately with a batch ID. Results must be retrieved by polling the status endpoint.
- sync: Waits for processing to complete, which may take 15-20 seconds per candidate.
Response (Async Mode)
{
"candidates": [],
"job": {
"candidate_count": 1,
"company": "Test Company Inc.",
"status": "active",
"title": "Senior Software Engineer",
"verda_id": 24
},
"processing": {
"batch_id": "batch_0a96c1e79579",
"estimated_completion_time": "2s",
"mode": "async",
"status": "processing",
"status_url": "/api/v1/ats/status/batch_0a96c1e79579"
},
"request_id": "req_dac3181f"
}
Response (Sync Mode)
{
"relevance_score": 85.5,
"matching_skills": ["Python", "JavaScript", "AWS"],
"experience_analysis": "The candidate has 5 years of relevant experience in software development, with a focus on backend systems and cloud architecture. Their experience leading development teams at ABC Company aligns well with the leadership aspect of this role.",
"education_analysis": "The candidate has a Bachelor's degree in Computer Science, meeting the educational requirements for this position.",
"skills_analysis": "The candidate demonstrates strong skills in Python, JavaScript, and cloud technologies (AWS), which directly match the job requirements. Their experience with microservices architecture is particularly relevant.",
"overall_analysis": "Overall, this candidate shows strong alignment with the job requirements, particularly in technical skills and leadership experience. With 5+ years of relevant experience and a matching technical stack, they appear to be a good fit for the Senior Software Engineer position."
}
Implementation Example (Python)
import requests
import json
import time
from uuid import uuid4
def process_candidates(api_key, job_data, candidate_data, mode="async"):
"""
Process candidates against a job using the Assess API
Args:
api_key: Your Verda API key
job_data: Dictionary with job title, description, etc.
candidate_data: List of dictionaries with candidate details
mode: "async" or "sync" processing mode
Returns:
Response JSON from the API
"""
# API endpoint
url = 'https://verda.work/api/v1/ats/process'
# Request headers
headers = {
'X-API-Key': api_key,
'Content-Type': 'application/json'
}
# Request payload
payload = {
"job": job_data,
"candidates": candidate_data,
"processing_options": {
"mode": mode
}
}
# Make API request
if mode == "async":
timeout = 10 # seconds
else:
timeout = 30 # seconds per candidate
response = requests.post(
url,
headers=headers,
json=payload,
timeout=timeout
)
# Handle async mode (check status)
if mode == "async" and response.status_code == 202:
data = response.json()
batch_id = data['processing']['batch_id']
status_url = data['processing']['status_url']
print(f"Async process initiated. Batch ID: {batch_id}")
print(f"Status URL: {status_url}")
# You would implement status polling here
return response.json()