Alfa

Alfa API · v1

Alfa API

Connect an applicant tracking system (ATS) to Alfa. Send Alfa your jobs, and get back every candidate Alfa screens or sources for them, with a status, a score and a summary. Your server calls the API with an API key; no user signs in.

Two ways to connect

You areUseHow it works
A company connecting its own ATSA company keyYour org admin generates the key in Alfa, in Settings › Developers. It acts for your company only.
An ATS platform serving many client companiesA platform keyAlfa issues the key to your platform. Each client company authorizes your platform in Alfa, and every request names the client company it is for. Read about platform keys.

Both key types call the same endpoints and receive the same webhooks.

How it works

  1. Your ATS sends a jobPUT /v1/integration/ats-jobs/{externalJobId} creates or updates it under your own job id.
  2. A recruiter links itIn the Alfa job form, a recruiter picks your job from the ATS job picker.
  3. Alfa finds and screens candidatesApplicants are screened, and Alfa sources candidates who fit the job.
  4. Alfa reports backA webhook arrives for each candidate and each later status change. You can also poll GET /v1/integration/candidates/page.

Only Alfa jobs linked to an ATS job produce candidates and events. Platform keys can also send applicants into Alfa with applicant intake.

Candidate statuses

Every candidate on a linked job has one status. Applicant ids start app_, and ids of candidates Alfa sourced start src_.

StatusMeaning
shortlistedA recruiter shortlisted the candidate. This outranks the screening outcome.
suitableScreening found the candidate suitable for the job.
not_suitableScreening found the candidate not suitable for the job.
sourced_potentialA candidate Alfa sourced who fits the job.

Hosts

  • Production: https://api.welovealfa.com, with live keys (alfa_live_…).
  • Development: https://dev-api.welovealfa.com, with test keys (alfa_test_…).

Every path starts /v1/integration. Bodies are JSON. Errors are problem details objects with a code (error codes and rate limits), long lists are paged with a cursor, and applicant intake accepts an idempotency key.

Versioning

The version is part of the path, /v1. New fields, events and endpoints are added without notice and are not breaking changes, so ignore fields you do not know. A breaking change ships as /v2, announced at least 6 months ahead, and the old version sends Deprecation and Sunset headers until it is removed. The changelog lists every change.

Guides and reference