Aptly Intelligence API

CV screening,
as an API.

Add AI-powered candidate scoring to any ATS or HR platform. Submit a job spec and CVs — get structured scores, match reasoning, and gap analysis back in seconds.

Get your API key → View docs
<5s
Per candidate, at scale
200
CVs per request
72h
Results retained
Request / Response
POST https://aptly-backend-unk2.onrender.com/api/v1/screen X-API-Key: aptly_your_key_here Content-Type: application/json { "job_spec": "Senior Python Developer...", "candidates": [ { "candidate_ref": "your-internal-id-001", "cv_text": "7 years Python experience..." } ], "webhook_url": "https://yourapp.com/webhook" } → Returns job_id immediately. Results ready in seconds.
How it works

Submit once.
Results delivered.

A simple async flow designed to handle large batches without blocking your application.

01
🔑
Authenticate
Generate an API key from your Aptly account. Pass it in the X-API-Key header on every request.
02
📤
Submit
POST your job spec and an array of candidates. Each candidate needs a candidate_ref — your internal ID, echoed back in results.
03
⚡
Processing
Aptly scores each CV in parallel batches using Claude. Up to 200 candidates per request, processed in under a minute at scale.
04
📬
Retrieve
Poll GET /api/v1/jobs/{job_id} or receive results via webhook. Results include score, verdict, match reasons, and gaps per candidate.
Use cases

Built for teams who
move fast.

Wherever you have CVs and a job description, the Intelligence API fits in.

🗂️
ATS integration
Add AI scoring to your existing applicant tracking system without rebuilding your infrastructure. Hook into your application pipeline and get scores back within seconds of receipt.
🏢
Corporate HR platforms
Large organisations with internal hiring portals can screen at volume without manual review bottlenecks. Score hundreds of applicants overnight before a recruiter starts their day.
🔁
Batch rescreening
Rescreen your existing candidate database against a new role specification. Find matches you already have before advertising externally.
📊
Recruitment analytics
Feed structured scoring data into your own dashboards and reporting tools. Track candidate quality trends, pipeline conversion, and sourcing effectiveness over time.
🧩
White-label products
Building a recruitment product? The Intelligence API gives you a production-ready scoring engine so you can focus on your own product layer rather than the AI infrastructure.
⚙️
Automated workflows
Trigger screening automatically when a job closes, when a candidate threshold is reached, or on a schedule. Full webhook support means results arrive in your system the moment they're ready.
Response structure

Structured scoring,
every time.

Every scored candidate returns the same predictable structure. No prompt engineering on your side required.

{ "candidate_ref": "your-internal-id", "score": 84, "verdict": "Strong shortlist", "match_reasons": [ "7 years Python meets the senior band", "FastAPI experience directly matches stack", "Led distributed teams of 6+ engineers" ], "gaps": [ "No AWS infrastructure experience mentioned", "No mention of system design at scale" ] }
candidate_ref string
Your internal identifier echoed back exactly as submitted. Use this to map results back to your own records.
score integer 0–100
Absolute fit score against the job specification. 75+ is strong, 50–74 borderline, below 50 is not recommended to progress.
verdict enum
One of: Strong shortlist, Borderline, or Do not progress. Consistent across all responses.
match_reasons string[]
Up to 4 specific, evidence-based reasons this candidate fits the role. Always references actual CV content, never generic.
gaps string[]
Up to 3 specific gaps to probe or disqualifying factors. Gives your team something concrete to act on in an interview or decline decision.
Pricing

Pay for what
you screen.

All plans require an active Aptly subscription. Unused CVs expire monthly — no rollover.

Starter
$199/mo
1,000 CVs included
  • $0.18 per CV over included
  • Up to 200 CVs per request
  • Async processing with polling
  • Webhook delivery
  • 72-hour result retention
  • 5 API keys
  • Standard support
Get started →
Most popular
Business
$499/mo
3,500 CVs included
  • $0.15 per CV over included
  • Up to 200 CVs per request
  • Async processing with polling
  • Webhook delivery with 3 retries
  • 72-hour result retention
  • 5 API keys
  • Priority support
Get started →
Enterprise
Custom
Volume pricing
  • Custom CV volume and pricing
  • Dedicated processing capacity
  • Extended result retention
  • Custom webhook configuration
  • SLA with uptime guarantee
  • Unlimited API keys
  • Dedicated support
Contact us →

All prices in USD. Requires active Aptly Starter, Pro, or Agency subscription. Full API reference →

Common questions

Everything you
need to know.

If something isn't covered here, email us at hello@aptly.pro.

What format do CVs need to be in?
Plain text only. Your application is responsible for extracting text from PDFs or Word documents before submitting. This keeps the API fast and avoids binary transfer overhead.
How long do results take?
Single candidates typically score in 3–5 seconds. Batches of 50 candidates usually complete in under 60 seconds. Processing is parallel so larger batches don't scale linearly.
What happens to candidate data?
Results are stored for 72 hours then permanently purged. We process but do not retain CV text beyond what's required to generate the score. Your data is not used to train models.
Can I send duplicate candidate_ref values?
Not within a single request. All candidate_ref values must be unique per submission. Across separate requests to different jobs, the same ref is fine.
What is the maximum batch size?
200 candidates per request. For larger volumes, split into multiple requests and process them in parallel. There is no limit on the number of concurrent requests.
Do I need an Aptly account to use the API?
Yes. An active Aptly subscription is required to generate API keys. The Intelligence API is an add-on product, not a standalone offering. This lets us maintain quality and prevent abuse.
How does webhook delivery work?
If you provide a webhook_url in your request, we POST the completed results to that URL when processing finishes. We retry 3 times with exponential backoff if your endpoint is unavailable.
Is there a free tier or trial?
There's no standalone free tier for the API, but all Aptly accounts include the full screening UI which uses the same underlying scoring engine. This lets you evaluate quality before committing to the API product.

Start screening in
under 5 minutes.

Create an Aptly account, generate your API key, and make your first request. No sales call, no waiting list.

Create account and get API key → Talk to us