# AI Candidate Finder - Find Candidates from a Job Description (`ayk_6789/ai-candidate-finder`) Actor

Find relevant LinkedIn candidates from any job description. AI searches, evaluates, scores, and ranks profiles by skills, experience, seniority, and location.

- **URL**: https://apify.com/ayk\_6789/ai-candidate-finder.md
- **Developed by:** [YKA](https://apify.com/ayk_6789) (community)
- **Categories:** Jobs, AI, Lead generation
- **Stats:** 1 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: 4.00 out of 5 stars

## Pricing

from $500.00 / 1,000 ai-evaluated candidates

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## LinkedIn Candidate Matcher — AI Candidate Search & Ranking

Find and rank relevant LinkedIn candidates directly from a Job Description.

**LinkedIn Candidate Matcher** analyzes your hiring requirement, searches for potentially relevant LinkedIn profiles, evaluates each candidate against the Job Description, and returns a ranked shortlist with an AI-generated **match score from 0–100**.

Instead of manually searching through dozens of profiles, provide the role requirements and let the Actor handle the initial candidate discovery and prioritization.

***

### What this Actor does

Given a Job Description, this Actor:

1. Analyzes the **Job Description (JD)** using AI.
2. Generates an optimized candidate-search query.
3. Searches for potentially relevant LinkedIn profiles.
4. Validates and deduplicates discovered profiles.
5. Evaluates each candidate against the JD.
6. Scores each candidate from **0–100**.
7. Explains **why the candidate matched or did not strongly match**.
8. Categorizes candidates into:

   - `above_70`
   - `50_to_70`
   - `below_50`
9. Ranks candidates from strongest to weakest.
10. Writes one structured record per candidate to the Apify **Dataset**.
11. Makes results available for export or API consumption.

***

### Example

Suppose you're hiring a:

> **Junior Data Scientist — London, United Kingdom**

with requirements including:

- 1–2 years of Data Science / ML / AI experience
- Strong Python
- Machine Learning fundamentals
- Pandas / NumPy / Scikit-learn
- PyTorch, TensorFlow, or similar
- Exposure to NLP
- Exposure to LLMs / Generative AI
- Embeddings and retrieval
- London-based / hybrid availability

Provide those requirements to the Actor.

The Actor searches for potentially relevant profiles and evaluates them against the role.

A real test run returned candidates across multiple match levels:

```text id="m0eqcw"
Rank    Match    Band
────────────────────────────
#1      85       above_70
#2      85       above_70
#3      65       50_to_70
#4      65       50_to_70
#5      65       50_to_70
#6      65       50_to_70
#7      65       50_to_70
#8      45       below_50
#9      45       below_50
#10     45       below_50
#11     45       below_50
#12     35       below_50
#13     35       below_50
#14     35       below_50
#15     25       below_50
```

The goal is not simply to find profiles.

The goal is to help recruiters identify **which discovered profiles deserve attention first**.

***

## Input

The Actor accepts the following hiring information.

### Job title

The target role.

Example:

```text id="2u0p6d"
Junior Data Scientist - London
```

### Job description

Paste the complete Job Description.

Example:

```text id="42mpw4"
Junior Data Scientist | London | £50k + Bonus

We are looking for a Junior Data Scientist to join a growing
technology team.

The role involves:

- Machine Learning, NLP and Generative AI
- LLMs, embeddings and retrieval
- Classification, regression and clustering
- Semantic search and recommendations
- Python-based ML pipelines

Requirements:

- 1-2 years of Data Science / ML / AI experience
- Strong Python
- Solid Machine Learning fundamentals
- Pandas, NumPy and Scikit-learn
- PyTorch/TensorFlow or similar
- Exposure to LLMs / Generative AI
```

### Location

Example:

```text id="brkmzq"
London, United Kingdom
```

### Experience level

Example:

```text id="1t76qr"
1-2 years
```

### Candidate limit

Choose how many candidate profiles should be processed.

For example:

```text id="ez3n6b"
15
```

For testing, using a smaller candidate limit can reduce processing time and usage cost.

***

## How it works

```text id="qhmj84"
Job Description
       ↓
AI Requirement Analysis
       ↓
Search Query Generation
       ↓
LinkedIn Candidate Discovery
       ↓
Profile Validation
       ↓
Deduplication
       ↓
Candidate Evaluation
       ↓
AI Match Score
       ↓
Match Explanation
       ↓
Candidate Ranking
       ↓
Apify Dataset
```

***

## Candidate evaluation

Each candidate is compared against the supplied Job Description.

Depending on the information available in the discovered profile, the evaluation may consider signals such as:

- Current job title
- Previous roles
- Relevant professional experience
- Career stage
- Seniority
- Skills
- Machine Learning / AI experience
- Industry relevance
- Location
- Role alignment
- Required technologies
- Other requirements identified from the JD

The Actor then assigns a **match score between 0 and 100**.

***

## Match bands

Candidates are grouped into three bands.

|  Score | Band       | Meaning                  |
| -----: | ---------- | ------------------------ |
| 71–100 | `above_70` | Strong potential match   |
|  50–70 | `50_to_70` | Moderate potential match |
|   0–49 | `below_50` | Lower potential match    |

Candidates are automatically ranked from highest to lowest match score.

***

## Why the candidate matched

Every candidate includes a `why_matched` field.

This provides short AI-generated explanations showing which available profile signals influenced the candidate's score.

For example:

```json id="5fnns7"
{
  "rank": 1,
  "match_score": 85,
  "match_band": "above_70",
  "why_matched": [
    "Candidate is currently based in London, matching the job location requirement.",
    "Current Machine Learning role provides hands-on experience with ML pipelines and production models.",
    "Career stage appears consistent with the early-career requirement."
  ]
}
```

The explanation can also identify apparent gaps.

For example:

```json id="g1yjrf"
{
  "match_score": 45,
  "match_band": "below_50",
  "why_matched": [
    "Relevant academic or internship experience is present.",
    "Professional experience appears below the requested 1-2 years.",
    "Current seniority does not strongly align with the requirement."
  ]
}
```

This makes it easier to understand **why one candidate was ranked above another**.

***

## Output

Each candidate is stored as an individual record in the Apify Dataset.

Example:

```json id="huzbjh"
{
  "rank": 1,
  "candidate_name": "Candidate Name",
  "match_score": 85,
  "match_band": "above_70",
  "profile_title": "Candidate Name",
  "linkedin_url": "https://linkedin.com/in/example",
  "why_matched": [
    "Candidate location matches the job requirement.",
    "Current role provides relevant Machine Learning experience.",
    "Career stage aligns with the Junior role."
  ],
  "job_id": "01",
  "evaluated_at": "2026-08-23T17:47:06.986Z"
}
```

***

## Output fields

| Field            | Description                               |
| ---------------- | ----------------------------------------- |
| `rank`           | Candidate's final ranking                 |
| `candidate_name` | Candidate name                            |
| `linkedin_url`   | Discovered LinkedIn profile URL           |
| `match_score`    | AI-generated match score from 0–100       |
| `match_band`     | Candidate match category                  |
| `why_matched`    | Reasons supporting the score              |
| `job_id`         | Identifier associated with the search     |
| `evaluated_at`   | Candidate evaluation timestamp            |
| `profile_title`  | Profile title/name returned by the search |

***

## Example: strong candidate

A candidate may receive a high score when multiple important requirements align.

```text id="cew2a9"
Match Score: 85/100
Band: above_70

✓ London location
✓ Relevant Machine Learning role
✓ ML pipeline experience
✓ Appropriate early-career profile
✓ Relevant technical background
```

***

## Example: moderate candidate

A candidate may have relevant experience while missing some requirements.

```text id="qngyfj"
Match Score: 65/100
Band: 50_to_70

✓ London location
✓ AI/ML-related role
✓ Relevant technical exposure

△ Limited professional experience
△ Some required skills not visible in available profile data
```

***

## Example: weak candidate

The Actor can also identify profiles that should receive lower priority.

```text id="3g02qk"
Match Score: 35/100
Band: below_50

✓ Data Science experience

✗ Location mismatch
✗ Experience requirement mismatch
✗ Limited evidence for some required technologies
```

This prevents candidate discovery from becoming a simple collection of LinkedIn URLs.

***

## Use cases

### Recruiters

Turn a Job Description into an initial candidate shortlist.

```text id="slb5dn"
Job Requirement
      ↓
Candidate Matcher
      ↓
Ranked Candidates
      ↓
Recruiter Review
```

### HR teams

Use the Actor to reduce manual effort during the first stage of candidate sourcing.

Instead of reviewing every discovered profile equally, start with candidates that appear most aligned with the requirement.

### Recruitment agencies

Process requirements from multiple clients.

```text id="9v8ioy"
Client JD
   ↓
Run Actor
   ↓
Ranked Candidate Dataset
   ↓
Recruiter Review
   ↓
Candidate Outreach
```

### Recruiting automation developers

Use the Actor as a candidate discovery and ranking component.

```text id="6fvg2p"
New Job Requirement
        ↓
Run Actor through API
        ↓
Candidate Dataset
        ↓
ATS / CRM / Google Sheets
        ↓
Recruiter Review
```

***

## Exporting results

Candidate results are stored in the Apify Dataset.

They can be consumed through supported Dataset exports and APIs for downstream workflows.

Possible destinations include:

- Google Sheets
- ATS platforms
- CRM systems
- Internal HR tools
- Recruiting dashboards
- n8n
- Make
- Zapier
- AI agents
- Custom applications

***

## API & automation

The Actor can also be run programmatically through Apify.

This makes it possible to build workflows such as:

```text id="9uyimc"
ATS receives new job
        ↓
Trigger Actor
        ↓
Discover candidates
        ↓
Score candidates
        ↓
Return top candidates
        ↓
Store results
        ↓
Recruiter reviews shortlist
```

***

## Important limitations

Candidate scores and explanations are **AI-generated estimates based on the information available during candidate discovery**.

A high score does not guarantee that a candidate:

- Meets every requirement
- Possesses every inferred skill
- Is currently looking for employment
- Is interested in the position
- Is available for the role
- Is eligible to work in the required location
- Will pass an interview
- Is ultimately suitable for employment

Some professional information may be incomplete, outdated, ambiguous, or unavailable.

The Actor should therefore be used for:

**Candidate discovery → prioritization → human review**

and not as an automated final hiring or rejection system.

***

## Responsible use

Users are responsible for ensuring their use of the Actor and its output complies with applicable laws, privacy requirements, employment regulations, platform terms, and anti-discrimination requirements.

Do not use protected or sensitive personal characteristics to make employment decisions.

Human review is recommended before contacting, interviewing, rejecting, or making employment decisions involving candidates.

***

## FAQ

### What do I need to provide?

Provide:

- Job title
- Job description
- Location
- Experience level
- Candidate limit

The Actor handles candidate discovery, evaluation, scoring, and ranking.

### Do I need to create LinkedIn search queries myself?

No.

The Actor generates candidate-search queries based on the supplied hiring requirement.

### Does the Actor return LinkedIn profiles?

When a valid LinkedIn profile is discovered, its URL is returned in the candidate record.

### How are candidates scored?

Candidate information available during discovery is evaluated against requirements extracted from the Job Description.

The Actor assigns a score between **0 and 100**.

### What does `above_70` mean?

It indicates that the candidate appears to have relatively strong alignment with the supplied requirement based on available information.

It does not guarantee suitability.

### Why did a candidate receive a low score?

Potential reasons can include:

- Location mismatch
- Insufficient experience
- Excessive seniority
- Job-title mismatch
- Missing technical skills
- Limited evidence of relevant experience
- Industry mismatch

### Can the Actor detect overqualified candidates?

The evaluation can consider seniority and experience alignment.

For example, a Senior Data Scientist may receive a lower score when the requirement specifically calls for a Junior Data Scientist with 1–2 years of experience.

### Can I export the results?

Yes.

Candidate records are stored in the Apify Dataset and can be exported or accessed programmatically.

### Can I connect this Actor to my ATS?

The structured output and Apify API make it possible to incorporate the Actor into external recruiting workflows. The exact integration depends on the target ATS.

### Should I automatically reject candidates with low scores?

No.

Scores should be treated as prioritization signals.

Human review should be used for hiring and rejection decisions.

***

## Who is this for?

This Actor is designed for:

- Recruiters
- HR professionals
- Talent acquisition teams
- Recruitment agencies
- Staffing companies
- Sourcing specialists
- HR technology developers
- Recruiting automation builders

***

## LinkedIn Candidate Matcher

**Job Description → Candidate Discovery → AI Evaluation → Ranked Shortlist**

Spend less time searching through profiles and more time reviewing the candidates most relevant to your requirement.

# Actor input Schema

## `jobId` (type: `string`):

Optional identifier for this requisition. Auto-generated if left blank.

## `jobTitle` (type: `string`):

Role title, used for display and reporting only.

## `description` (type: `string`):

Full JD text to analyze. Please paste plain text only - do not include emojis or special/decorative characters (e.g. 🚨, 🔍, •, ➤); they will be stripped automatically but plain text gives the most reliable results.

## `location` (type: `string`):

e.g. 'San Francisco, CA' or 'Chicago metro area'.

## `experienceLevel` (type: `string`):

e.g. 'Entry level', '3-5 years', 'Senior'. Used for display and reporting only.

## `candidateLimit` (type: `integer`):

Maximum number of candidate profiles to source and score for this job.

## Actor input object example

```json
{
  "jobTitle": "Not specified",
  "experienceLevel": "Not specified",
  "candidateLimit": 15
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `summary` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("ayk_6789/ai-candidate-finder").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("ayk_6789/ai-candidate-finder").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call ayk_6789/ai-candidate-finder --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,ayk_6789/ai-candidate-finder"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/2p8nmzh26BMvKtF9G/builds/Ipczlr1XgWii6ILwx/openapi.json