Candidates

Get a candidate

GET/v1/integration/candidates/{candidateId}

A screened candidate on a linked job, as webhooks send it. An unscreened candidate, or one from another company, is 404. Requires an API key with the `candidates:read` scope.

Requires an Alfa API key as a bearer token. How API keys work

Path parameters

  • candidateIdstringrequired

    Alfa's id for the candidate: `app_…` or `src_…`.

    at least 1 characters · at most 40 characters

Headers

  • Alfa-Company-Idstring

    The 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

  • candidateIdstringrequired

    Alfa's id for the candidate: `app_…` for an applicant, `src_…` for a candidate Alfa sourced.

  • externalCandidateIdstring | nullrequired

    Your candidate id, for applicants you sent through applicant intake.

  • externalApplicationIdstring | nullrequired

    Your application id, for applicants you sent through applicant intake.

  • firstNamestring | nullrequired

    First name.

  • lastNamestring | nullrequired

    Last name.

  • emailstring | nullrequired

    Email address.

  • phonestring | nullrequired

    Phone number, when known.

  • linkedinUrlstring | nullrequired

    LinkedIn 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"required

    Where 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.

  • statusUpdatedAtstringrequired

    When the status last changed. Keep the newest one you receive.

  • scorenumber | nullrequired

    The candidate score from 0 to 100; for a sourced candidate, the sourcing score.

  • summarystring | nullrequired

    Alfa's summary of the candidate against the job.

  • resumeUrlstring | nullrequired

    A signed link to the resume PDF, valid for 24 hours. Null when there is none.

  • profileUrlstringrequired

    The candidate's page in Alfa, for signed-in recruiters.

  • interviewobject | nullrequired

    The candidate's AI Interview, on jobs that interview applicants. Null until it is completed.

    Show fields
    • completedAtstringrequired

      When the candidate finished the AI Interview.

    • durationSecondsinteger | nullrequired

      How long the interview lasted.

    • audioOnlybooleanrequired

      Whether the candidate took the interview without video.

    • videoUrlstring | nullrequired

      A signed link to the interview recording, valid for 24 hours. Null until the recording is ready.

    • chaptersobject[]required

      The recording split into topics.

      Show fields
      • startSecondsnumberrequired

        Where the chapter starts in the recording.

      • titlestringrequired

        What the candidate talks about.

    • transcriptobject[]required

      The interview, turn by turn.

      Show fields
      • speaker"interviewer" | "candidate"required

        `interviewer` for Alfa's AI interviewer, `candidate` for the candidate.

      • textstringrequired

        What was said.

      • startSecondsnumberrequired

        When it was said, from the start of the recording.

  • resumeobject | nullrequired

    The 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 | nullrequired

      The current or most recent job title.

    • currentEmployerstring | nullrequired

      The current employer.

    • locationstring | nullrequired

      Where the candidate lives.

    • yearsExperiencenumber | nullrequired

      Years of work experience.

    • summarystring | nullrequired

      The resume's own summary.

    • skillsstring[]required

      Skills listed on the resume.

    • experienceobject[]required

      Work history, most recent first.

      Show fields
      • employerstring | nullrequired

        The employer.

      • titlestring | nullrequired

        The job title.

      • locationstring | nullrequired

        Where the job was.

      • startDatestring | nullrequired

        When it started, as written on the resume.

      • endDatestring | nullrequired

        When it ended; null for a current job.

      • descriptionstring | nullrequired

        What the candidate did.

    • educationobject[]required

      Education.

      Show fields
      • institutionstring | nullrequired

        The school or university.

      • degreestring | nullrequired

        The qualification.

      • fieldOfStudystring | nullrequired

        The subject.

      • startYearstring | nullrequired

        When it started.

      • endYearstring | nullrequired

        When it ended.

    • qualificationsobject[]required

      Certificates and licenses.

      Show fields
      • namestring | nullrequired

        The certificate or licence.

      • issuerstring | nullrequired

        Who issued it.

    • languagesstring[]required

      Languages, with proficiency when stated.

  • jobIdintegerrequired

    Alfa's id for the job.

  • externalJobIdstring | nullrequired

    The ATS job the Alfa job is linked to.

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