[Cotlet](https://cotlet.dev/index.md) · [Integrations](https://cotlet.dev/integrations.md) · [How it works](https://cotlet.dev/how-it-works.md) · [Use cases](https://cotlet.dev/use-cases.md) · [Security](https://cotlet.dev/security.md) · [For developers](https://cotlet.dev/for-developers.md) · [For automation agencies](https://cotlet.dev/for-agencies.md) · [Blog](https://cotlet.dev/blog.md) · [API docs](https://cotlet.dev/docs.md) · [Help center](https://cotlet.dev/help.md) · [Changelog](https://cotlet.dev/changelog.md) · [Contact](https://cotlet.dev/contact.md) · [Pricing](https://cotlet.dev/pricing.md) · [Sign up](https://cotlet.dev/signup)

# Build a JobDiva candidate hotlist for a new job

> Turn a new JobDiva job into a Talent Search, read the matches and fill a hotlist linked to the job, so you start from a shortlist.

Source: https://cotlet.dev/integrations/jobdiva-api-mcp-server/build-candidate-hotlist

A new job reaches a recruiter, and the first hour goes on searching the database, opening records and collecting the right people in one place.

Cotlet does it in your own JobDiva account with get\_job, search\_candidates, get\_candidate, list\_hotlists, create\_hotlist and add\_candidates\_to\_hotlist, called by your AI agent, an n8n workflow or a script.

[Sign up free](https://cotlet.dev/app/signup?app=jobdiva) [All JobDiva tools](https://cotlet.dev/integrations/jobdiva-api-mcp-server.md)

Hosted · nothing to install or maintain

## Can JobDiva do this on its own?

JobDiva runs Talent Search and hotlists inside the app, and its API has endpoints for both (checked 23 Oct 2026). The API needs a client ID that JobDiva provides, has no webhooks and comes with no MCP server, so an agent working for one recruiter has no ready route to it.

## How you do it in JobDiva today

1. The recruiter opens the job and reads the required skills, the years of experience and the location.
2. In Talent Search the recruiter types the skills and titles, then a location and a distance in miles.
3. The recruiter reads the result list and opens candidate records one by one to check work history and earlier notes.
4. The chosen candidates go into a hotlist, created first when the job has none.
5. The same search runs again when the job reopens or new resumes arrive, because JobDiva makes emailed resumes searchable within minutes.

## How to build a JobDiva candidate hotlist for a new job

Prompt

```
For job 24071835, run a Talent Search for SQL and dbt within 25 miles of Chicago, read the best matches, and put the ones that fit into a new hotlist linked to the job.
```

1. 01  
### Read the job first  
get\_job returns the title, company, location and the job reference. The agent checks that the job is the one you meant, and takes the skills and the radius from your prompt when the job text is short.
2. 02  
### Search with the job's own terms  
search\_candidates runs the search with skills, titles, a location and a radius. When the first page is thin, the agent widens the radius or drops the least important skill, and tells you what it changed.
3. 03  
### Read before choosing  
get\_candidate opens the best matches and returns work history, location and status. The agent keeps people whose history shows the skills for the years you asked for, and drops duplicates of the same person.
4. 04  
### Reuse or create the hotlist  
The agent checks list\_hotlists for a hotlist with the job's name before it makes a new one. create\_hotlist links the new hotlist to the job, so the recruiter finds it from the job record.
5. 05  
### Add the picks  
add\_candidates\_to\_hotlist puts your approved picks into the hotlist in one call. The agent reports how many were added and how many were already in it.

### What you get back

Example data

```
Job 24071835: Senior Data Analyst, Northwind Logistics
Talent Search matches: 31
Records read: 8
Hotlist "Senior Data Analyst - Northwind" created, linked to the job
Added 3:
- Priya Raman: 6 years SQL and dbt, Chicago
- Marcus Lee: BI lead, Naperville
- Elena Petrova: analytics engineer, Evanston
```

### Other ways to ask

- Every Monday, rerun the search for each of my open jobs and add new matches to the job's hotlist.
- Show me the top ten Talent Search matches for job 24071835 and add nobody.
- Search for candidates within 50 miles of Austin with the title "Data Engineer" and add the five most recent to the hotlist "Austin pipeline".

## What JobDiva allows, and what to know first

- JobDiva's Talent Search takes skills, titles, a location and a distance in miles, and its API spec also lists states, countries, qualifications and advanced skills as filters.
- JobDiva says its patented search ranks skills by relevant years of experience, so the years in your prompt change who comes first.
- JobDiva says resumes emailed or sent by FTP to the account become searchable in less than five minutes.
- A JobDiva candidate hotlist can be linked to a job and a hiring manager, and shared with users, groups or divisions.
- JobDiva keeps hotlists for contacts apart from hotlists for candidates, so a client contact never lands in a candidate hotlist.

create\_hotlist and add\_candidates\_to\_hotlist change only your own JobDiva data and reach no one else, so they run without asking first.

Sources: [JobDiva API (Swagger UI, Version 2)](https://api.jobdiva.com/jobdiva-api.html) · [JobDiva: Operational efficiency](https://www.jobdiva.com/operational-efficiency) · [JobDiva: FAQ](https://www.jobdiva.com/faq)

## Call add\_candidates\_to\_hotlist from a script

curl

```
curl -X POST https://cotlet.dev/api/v1/jobdiva/hotlists/88314/candidates-to-hotlists \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"candidate_ids":[5821904,5830117,5834402]}'
```

Example response

```
{
"hotlist_id": 88314,
"added": 3,
"hotlist_size": 3
}
```

MCP: add https://cotlet.dev/mcp/v1 with the same key; the call is jobdiva\_write → add\_candidates\_to\_hotlist. Example data.

[Schedule it in n8n, Make, Zapier or cron](https://cotlet.dev/integrations/jobdiva-api-mcp-server.md#automations)

## JobDiva tools this automation uses

__Cotlet JobDiva tools used to build a JobDiva candidate hotlist for a new job__
| Tool | Parameters |
| ---------------------------- | ---------------------------------------------------- |
| get\_job | job\_id, reference |
| search\_candidates | skills, titles, location, within\_miles, limit, page |
| get\_candidate | candidate\_id |
| list\_hotlists | none |
| create\_hotlist | name, description, job\_id |
| add\_candidates\_to\_hotlist | hotlist\_id, candidate\_ids |

[All 14 JobDiva tools with descriptions](https://cotlet.dev/integrations/jobdiva-api-mcp-server.md#tools)

## Frequently asked questions

### Is it safe to connect JobDiva to Cotlet?

Yes. You sign in to JobDiva yourself, in your own Cloud Browser in the EU, and we never save your password. Your agents only get JobDiva once you enable it, every background request is listed, and the browser profile is stored encrypted with AES-256-GCM, the cipher 1Password uses for its vaults. The AI model never sees a login, posts and messages wait for your OK, and Disable for agents cuts access in one click. Independent scanners grade cotlet.dev A+ on Qualys SSL Labs, securityheaders.com and Mozilla Observatory; live results are on https://cotlet.dev/security.

## More JobDiva automations

- [Log call notes on JobDiva candidate records](https://cotlet.dev/integrations/jobdiva-api-mcp-server/log-call-notes.md)
- [Submit shortlisted candidates to a JobDiva job](https://cotlet.dev/integrations/jobdiva-api-mcp-server/submit-candidates-to-a-job.md)
- [JobDiva API and MCP server: every tool](https://cotlet.dev/integrations/jobdiva-api-mcp-server.md)
- [All use cases](https://cotlet.dev/use-cases.md)

## Give your agent access to JobDiva.

Free 7-day trial with 2,000 credits, no card needed. Cotlet is independent and not affiliated with JobDiva.

[Sign up free](https://cotlet.dev/app/signup?app=jobdiva)

---

Give your AI agents your signed-in browser.

**Product:** [Integrations](https://cotlet.dev/integrations.md) · [Use cases](https://cotlet.dev/use-cases.md) · [How it works](https://cotlet.dev/how-it-works.md) · [Pricing](https://cotlet.dev/pricing.md) · [Security](https://cotlet.dev/security.md)

**Resources:** [Blog](https://cotlet.dev/blog.md) · [API docs](https://cotlet.dev/docs.md) · [Help center](https://cotlet.dev/help.md) · [Changelog](https://cotlet.dev/changelog.md) · [GitHub](https://github.com/cotletdev/cotlet)

**Solutions:** [For developers](https://cotlet.dev/for-developers.md) · [For automation agencies](https://cotlet.dev/for-agencies.md)

**Company:** [About](https://cotlet.dev/about.md) · [AI info: company facts](https://cotlet.dev/ai-info.md) · [Contact](https://cotlet.dev/contact.md)

**Legal:** [Terms of service](https://cotlet.dev/terms) · [Privacy policy](https://cotlet.dev/privacy) · [Refund policy](https://cotlet.dev/refunds) · [Acceptable use](https://cotlet.dev/acceptable-use) · [Cookie policy](https://cotlet.dev/cookies) · [DPA](https://cotlet.dev/dpa) · [Subprocessors](https://cotlet.dev/subprocessors)

**Elsewhere:** [Status page](https://status.cotlet.dev) · [Cotlet on GitHub](https://github.com/cotletdev) · [Cotlet on X](https://x.com/cotletdev) · [Cotlet on LinkedIn](https://www.linkedin.com/company/cotletdev) · [Cotlet on Product Hunt](https://www.producthunt.com/products/cotlet) · [Cotlet on Crunchbase](https://www.crunchbase.com/organization/cotlet) · [Cotlet on SaaSHub](https://www.saashub.com/cotlet)

Cotlet.dev is built by Bart Krawczyk and Jake Slugocki, the founders of Take Group sp. z o.o., ul. Wincentego Janasa 4, 40-855 Katowice, Poland. KRS 0000871398, NIP 6342984273, VAT EU: PL6342984273. [About us](https://cotlet.dev/about.md)

Cotlet is an independent service. It is not affiliated with, endorsed by or sponsored by any of the products listed on this site. Product names are trademarks of their respective owners.