API ReferenceCandidates

List candidates

Returns a paginated list of candidates in your organization. Supports free-text search, filtering by job, pipeline stage, score range, applied-date range, and source.

Authentication

AuthorizationBearer

Supabase-issued user JWT. Send as Authorization Bearer header. Dedicated API keys are planned for a future release.

Query parameters

searchstringOptional

Free-text search across candidate name, email, and phone.

statusstringOptional
Filter by application status slug.
job_idstringOptionalformat: "uuid"
Only return candidates with an application to this job.
stageenumOptional
Filter by current pipeline stage slug.
sourcestringOptional

Comma-separated list of candidate source values (e.g. indeed, referral).

min_scoreintegerOptional

Minimum screening score (inclusive).

max_scoreintegerOptional

Maximum screening score (inclusive).

date_fromdateOptional

Only candidates who applied on or after this date (ISO 8601).

date_todateOptional

Only candidates who applied on or before this date (ISO 8601).

sort_byenumOptional
Sort field.
Allowed values:
sort_orderenumOptional
Allowed values:
pageintegerOptionalDefaults to 1

Page number (1-based).

limitintegerOptionalDefaults to 20
Page size.

Response

Paginated candidate list.
datalist of objectsOptional
paginationobjectOptional

Errors

400
Bad Request Error
401
Unauthorized Error