List job candidates
Candidates of one job with their stage, the date they entered it and the last activity.
GET https://cotlet.dev/api/v1/recruiterflow/job-candidates
read
Lists the candidates on one job, one page at a time, oldest in stage first. stage takes a stage name from get_job. status active is the default, disqualified returns candidates removed from the job with their reason. stage_since is when the candidate entered the current stage. last_activity is the newest entry in the Activity Log.
Parameters
| Name | Type | Description |
|---|---|---|
| job_id string required | string | Job id from list_jobs. |
| stage string | string | Stage name as get_job shows it. |
| status enum | enum | active (default) or disqualified. |
| limit integer | integer | 1 to 50. Default: 25. |
| cursor string | string | Next page cursor from the previous call. |
Request
curl "https://cotlet.dev/api/v1/recruiterflow/job-candidates?job_id=job_8c41d2" \
-H "Authorization: Bearer $COTLET_API_KEY"result = client.call("recruiterflow", "list_job_candidates", {"job_id":"job_8c41d2"})const result = await cotlet.call('recruiterflow', 'list_job_candidates', {"job_id":"job_8c41d2"});cotlet call recruiterflow list_job_candidates --data '{"job_id":"job_8c41d2"}'Example response
{
"candidates": [
{
"candidate_id": "771204",
"name": "Priya Nair",
"stage": "Phone Screen",
"stage_since": "2026-09-02",
"last_activity": {
"type": "email",
"direction": "outgoing",
"at": "2026-09-04T10:30:00Z"
}
},
{
"candidate_id": "771390",
"name": "Marcus Lee",
"stage": "Phone Screen",
"stage_since": "2026-10-14",
"last_activity": {
"type": "email",
"direction": "incoming",
"at": "2026-10-21T08:05:00Z"
}
}
],
"next_cursor": null
}