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 are | Use | How it works |
|---|---|---|
| A company connecting its own ATS | A company key | Your org admin generates the key in Alfa, in Settings › Developers. It acts for your company only. Read about connecting your own ATS. |
| An ATS platform serving many client companies | A platform key | Alfa 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. A platform can also create its clients' companies and AI Interview jobs itself, paid for with credits: read the AI Interview workflow.
How it works
- Your ATS sends a job
PUT /v1/integration/ats-jobs/{externalJobId}creates or updates it under your own job id. - A recruiter links itIn the Alfa job form, a recruiter picks your job from the ATS job picker.
- Alfa finds and screens candidatesApplicants are screened on their resume or an AI Interview, and Alfa sources candidates who fit the job.
- 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_.
| Status | Meaning |
|---|---|
shortlisted | A recruiter shortlisted the candidate. This outranks the screening outcome. |
suitable | Screening found the candidate suitable for the job. |
not_suitable | Screening found the candidate not suitable for the job. |
sourced_potential | A 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), and operations that create or spend accept an idempotency key.
Paging
Lists end in /page and return data and a nextCursor. Send nextCursor back as cursor for the next page; it is null on the last one. limit is 1 to 100 and defaults to 25. Treat a cursor as opaque: a changed one, or one sent with different filters, is 400 invalid_cursor.
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
- Quickstart: a first call in minutes
- Authentication: keys, scopes and rotation
- Connect your own ATS: what a company builds to connect its own ATS
- Advertise from your CRM: how an agency CRM has Alfa advertise and screen its jobs
- Platform keys: one integration for many client companies
- AI Interviews for your clients: the end-to-end workflow for a platform running AI Interviews for its clients
- Applicant intake: send applicants from your ATS
- Clients and credits: create your clients' companies and interview jobs, and report credit usage
- Webhooks: events, signatures and retries
- Changelog: what changed and when
- API reference: every operation and event