List candidates
List the candidates of one job, filtered by stage, tag or status.
GET https://cotlet.dev/api/v1/homerun/jobs/{job_id}/candidates
read
Returns each candidate with their ID, name, stage, origin (applied or sourced), tags, application date and whether the first reply is overdue. Disqualified candidates are returned only with status disqualified, as Homerun shows them in Table view only.
Parameters
| Name | Type | Description |
|---|---|---|
| job_id string required | string | Job ID from list_jobs. |
| stage string | string | Stage name as shown in get_job, for example Application. |
| tag string | string | Tag name from list_tags. |
| status string | string | active or disqualified. Default active. |
Request
curl https://cotlet.dev/api/v1/homerun/jobs/job_8c41d2/candidates \
-H "Authorization: Bearer $COTLET_API_KEY"result = client.call("homerun", "list_candidates", {"job_id":"job_8c41d2"})const result = await cotlet.call('homerun', 'list_candidates', {"job_id":"job_8c41d2"});cotlet call homerun list_candidates --data '{"job_id":"job_8c41d2"}'Example response
{
"candidates": [
{
"candidate_id": "ap_N4pQ8sT2vX6zB1cD3eF5",
"name": "Dana Whitfield",
"stage": "Application",
"origin": "applied",
"tags": [],
"applied_at": "2026-10-20",
"first_reply_overdue": true
},
{
"candidate_id": "ap_K2mP7rS1uW5yA9bC3dE6",
"name": "Priya Raman",
"stage": "Application",
"origin": "applied",
"tags": [
"shortlist"
],
"applied_at": "2026-10-18",
"first_reply_overdue": true
}
]
}