Alfa

Candidates

List candidates

GET/v1/integration/candidates/page

The 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

  • limitstring

    How many results to return, from 1 to 100. Defaults to 25.

  • cursorstring

    The `nextCursor` of the previous page. Leave it out for the first page.

    at least 1 characters · at most 2048 characters

  • updatedSincestring

    Only candidates whose status changed at or after this time.

    format date-time

  • jobIdstring

    Only candidates on this Alfa job.

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

  • dataobject[]required

    The results on this page.

    Show fields
    • 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.

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

    • jobIdintegerrequired

      Alfa's id for the job.

    • externalJobIdstring | nullrequired

      The ATS job the Alfa job is linked to.

  • nextCursorstring | nullrequired

    Pass 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