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.

<5s

Per candidate, at scale

200

CVs per request

72h

Results retained

Request / Response

POST https://api.aptly.pro/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.

🔑

Authenticate

Generate an API key from your Aptly account. Pass it in the X-API-Key header on every request.

📤

Submit

POST your job spec and an array of candidates. Each candidate needs a candidate_ref — your internal ID, echoed back in results.

⚡

Processing

Aptly scores each CV in parallel batches using Claude. Up to 200 candidates per request, processed in under a minute at scale.

📬

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.

Build

Up to 1,000 CVs/mo

Up to 200 CVs per request
Async processing with polling
Webhook delivery
72-hour result retention
5 API keys per organisation
Standard support

Scale

Up to 5,000 CVs/mo

Up to 200 CVs per request
Async processing with polling
Webhook delivery with 3 retries
72-hour result retention
5 API keys per organisation
Priority support

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

API access is provisioned manually for each customer. Contact us to discuss your volume and we'll set up your account. 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. The Intelligence API is an add-on to the Aptly platform, not a standalone product. Contact us to set up API access for your account.

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.

CV screening,as an API.

Submit once.Results delivered.

Built for teams whomove fast.

Structured scoring,every time.

Pay for whatyou screen.