JobDiva logo JobDiva automation

Build a JobDiva candidate hotlist for a new job

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 All JobDiva tools

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) · JobDiva: Operational efficiency · JobDiva: 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

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

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.

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