Candidates
List candidates
/v1/integration/candidates/pageThe polling alternative to webhooks: candidates on linked jobs whose status changed at or after `updatedSince`, oldest change first. Each is the same object a webhook sends. Store the last `statusUpdatedAt` you saw and pass it next time. Requires an API key with the `candidates:read` scope.
Requires an Alfa API key as a bearer token. How API keys work
Query parameters
limitstringHow many results to return, from 1 to 100. Defaults to 25.
cursorstringThe `nextCursor` of the previous page. Leave it out for the first page.
at least 1 characters · at most 2048 characters
updatedSincestringOnly candidates whose status changed at or after this time.
format date-time
jobIdstringOnly candidates on this Alfa job.
Headers
Alfa-Company-IdstringThe Company ID of the company to act for. Required with a platform key, and that company must have authorized your platform; a company key acts for its own company and can leave it out.
Response body
dataobject[]requiredThe results on this page.
Show fields
candidateIdstringrequiredAlfa's id for the candidate: `app_…` for an applicant, `src_…` for a candidate Alfa sourced.
externalCandidateIdstring | nullrequiredYour candidate id, for applicants you sent through applicant intake.
externalApplicationIdstring | nullrequiredYour application id, for applicants you sent through applicant intake.
firstNamestring | nullrequiredFirst name.
lastNamestring | nullrequiredLast name.
emailstring | nullrequiredEmail address.
phonestring | nullrequiredPhone number, when known.
linkedinUrlstring | nullrequiredLinkedIn profile URL, when known.
source"application" | "sourced"required`application` for an applicant, `sourced` for a candidate Alfa found and approached.
channel"linkedin" | "indeed" | "totaljobs" | "cv_library" | "glassdoor" | "monster" | "ziprecruiter" | "other_job_board" | "google" | "social_media" | "company_website" | "referral" | "ats" | "alfa_network" | "direct" | "sourced" | "other"requiredWhere the candidate came from: the job board or other channel an applicant applied through, `ats` for an applicant you sent, or `sourced` for a candidate Alfa found and approached. An applicant with no tracking is counted as `alfa_network`, or `direct` for a company that does not use Alfa outreach.
status"shortlisted" | "suitable" | "not_suitable" | "sourced_potential"required`shortlisted`: a recruiter shortlisted them. `suitable` or `not_suitable`: the screening outcome. `sourced_potential`: a sourced candidate who fits the job.
statusUpdatedAtstringrequiredWhen the status last changed. Keep the newest one you receive.
scorenumber | nullrequiredThe candidate score from 0 to 100; for a sourced candidate, the sourcing score.
summarystring | nullrequiredAlfa's summary of the candidate against the job.
resumeUrlstring | nullrequiredA signed link to the resume PDF, valid for 24 hours. Null when there is none.
profileUrlstringrequiredThe candidate's page in Alfa, for signed-in recruiters.
interviewobject | nullrequiredThe candidate's AI Interview, on jobs that interview applicants. Null until it is completed.
Show fields
completedAtstringrequiredWhen the candidate finished the AI Interview.
durationSecondsinteger | nullrequiredHow long the interview lasted.
audioOnlybooleanrequiredWhether the candidate took the interview without video.
videoUrlstring | nullrequiredA signed link to the interview recording, valid for 24 hours. Null until the recording is ready.
chaptersobject[]requiredThe recording split into topics.
Show fields
startSecondsnumberrequiredWhere the chapter starts in the recording.
titlestringrequiredWhat the candidate talks about.
transcriptobject[]requiredThe interview, turn by turn.
Show fields
speaker"interviewer" | "candidate"required`interviewer` for Alfa's AI interviewer, `candidate` for the candidate.
textstringrequiredWhat was said.
startSecondsnumberrequiredWhen it was said, from the start of the recording.
resumeobject | nullrequiredThe candidate's resume as structured data, read from the resume file. Null when Alfa holds no resume, which is always the case for a sourced candidate.
Show fields
headlinestring | nullrequiredThe current or most recent job title.
currentEmployerstring | nullrequiredThe current employer.
locationstring | nullrequiredWhere the candidate lives.
yearsExperiencenumber | nullrequiredYears of work experience.
summarystring | nullrequiredThe resume's own summary.
skillsstring[]requiredSkills listed on the resume.
experienceobject[]requiredWork history, most recent first.
Show fields
employerstring | nullrequiredThe employer.
titlestring | nullrequiredThe job title.
locationstring | nullrequiredWhere the job was.
startDatestring | nullrequiredWhen it started, as written on the resume.
endDatestring | nullrequiredWhen it ended; null for a current job.
descriptionstring | nullrequiredWhat the candidate did.
educationobject[]requiredEducation.
Show fields
institutionstring | nullrequiredThe school or university.
degreestring | nullrequiredThe qualification.
fieldOfStudystring | nullrequiredThe subject.
startYearstring | nullrequiredWhen it started.
endYearstring | nullrequiredWhen it ended.
qualificationsobject[]requiredCertificates and licenses.
Show fields
namestring | nullrequiredThe certificate or licence.
issuerstring | nullrequiredWho issued it.
languagesstring[]requiredLanguages, with proficiency when stated.
jobIdintegerrequiredAlfa's id for the job.
externalJobIdstring | nullrequiredThe ATS job the Alfa job is linked to.
nextCursorstring | nullrequiredPass as `cursor` to read the next page; null on the last page.
Responses
- 200Success.
- 400The request is malformed: invalid JSON, an unexpected body or an unknown query parameter. Problem details
- 401The bearer token is missing, expired or invalid. Problem details
- 403The caller may not perform this operation, or has no active organisation. Problem details
- 404The resource does not exist or is not visible to the caller. Problem details
- 422The request failed validation; `errors` lists each invalid field. Problem details
- 429Too many requests, or the AI service is busy. Retry after a short wait. Problem details
- 500An unexpected error. Quote the `correlationId` to support. Problem details