Alfa API

AI Interviews for your clients

Offer Alfa's AI Interview inside your ATS. Your platform creates each client and job in Alfa, sends every candidate a personal interview link, and receives the recording, transcript, summary and score when they finish. Your clients never sign in to Alfa, and every interview uses your platform's credits.

The workflow

Once per clientCreate the client company and set its webhook endpoint.
Once per jobCreate an interview job under your ATS job id.
For each candidateSend the application, and send the candidate the interview link Alfa returns.
When they finishAlfa sends the score, summary, recording, transcript and chapters to your webhook.

Before you start

Alfa issues your platform a test key (alfa_test_…) for the development API, https://dev-api.welovealfa.com, and a live key once you are ready. Each key is a platform key with these scopes:

Scope	Used to
`clients:write`	Create and list client companies.
`jobs:write`	Create, update and close interview jobs.
`applications:write`	Send candidates and get their interview links.
`webhooks:manage`	Set each client’s webhook endpoint.
`candidates:read`	Read candidates and fresh recording links.
`usage:read`	Read credit usage.

Every request after the first step names the client it is for in the Alfa-Company-Id header.

Give Alfa a technical contact email for your platform. If a client's webhook endpoint fails for 3 days, Alfa turns it off and emails that address, naming the client.

1. Create the client

Create a company in Alfa for each of your clients, under your own client id. Store the companyId it returns against that client. Sending the same externalClientId again returns the same client, so the call is safe to repeat.

Create a client

curl -X POST "https://dev-api.welovealfa.com/v1/integration/platform/clients" \
  -H "Authorization: Bearer $ALFA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"externalClientId":"tenant_42","name":"Acme Security Ltd"}'

Field	Required	Meaning
`externalClientId`	Required	Your id for the client. Sending it again returns the same client.
`name`	Required	The client company name.
`country`	Optional	Where the client is based.

2. Set the client's webhook endpoint

Each client has its own webhook endpoint: its own URL, signing secret and delivery log, so one client's events never reach another client's endpoint. Set it once, with the client's Alfa-Company-Id, and store the whsec_… secret from the response against the client. Each event also names its client in organizationId.

Set the webhook endpoint

curl -X PUT "https://dev-api.welovealfa.com/v1/integration/webhook-endpoint" \
  -H "Authorization: Bearer $ALFA_API_KEY" \
  -H "Alfa-Company-Id: org_2abcDEF123" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://ats.example.com/alfa/webhooks"}'

3. Create an interview job

Send each job under your own ATS job id. Alfa creates it live and unlisted: candidates reach it only through the links you send. The description is shown to candidates as written, and Alfa writes the scoring criteria from it. Send the job again to update it.

Create an interview job

curl -X PUT "https://dev-api.welovealfa.com/v1/integration/ats-jobs/job_8841/interview-job" \
  -H "Authorization: Bearer $ALFA_API_KEY" \
  -H "Alfa-Company-Id: org_2abcDEF123" \
  -H "Content-Type: application/json" \
  -d '{"title":"Security Officer","description":"We are hiring a Security Officer for our London office. You will patrol the site, monitor CCTV and respond to alarms.","status":"open"}'

The three required fields are enough to start interviewing. Add the optional ones when you want to change the defaults; on an update, an optional field you leave out keeps its value.

Field	Required	Meaning
`title`	Required	The job title.
`description`	Required	Shown to candidates as written. Alfa writes the scoring criteria and interview from it. Markdown is allowed.
`status`	Required	open, or closed to stop new applications.
`city, country`	Optional	Where the job is. Default: not set.
`workSetup`	Optional	Remote, Hybrid or On-site. Default: On-site.
`contractType`	Optional	Permanent, Contract or Temporary. Default: Permanent.
`allowInternational`	Optional	Whether candidates based outside the job’s country can pass. Default: true.
`language`	Optional	The interview language. Default: en-GB.
`interviewFormat`	Optional	both (the candidate chooses), video or audio. Default: both.
`interviewQuestions`	Optional	Questions asked word for word, before the questions about the role’s requirements. Default: none.

Interviews take about 4 minutes.
Send status: "closed" when the job closes. New applications are then refused with 409 job_not_accepting_applications.

4. Send each candidate

Send each application with your job, candidate and application ids. No resume is needed: the candidate is screened on the interview. The response carries the candidate's interviewUrl.

Send a candidate

curl -X POST "https://dev-api.welovealfa.com/v1/integration/applications" \
  -H "Authorization: Bearer $ALFA_API_KEY" \
  -H "Alfa-Company-Id: org_2abcDEF123" \
  -H "Content-Type: application/json" \
  -d '{"externalJobId":"job_8841","externalCandidateId":"cand_123","externalApplicationId":"appl_456","firstName":"Ada","lastName":"Lovelace","email":"ada@example.com"}'

Field	Required	Meaning
`externalJobId`	Required	Your ATS job id, as in step 3.
`externalCandidateId`	Required	Your id for the candidate, returned on every webhook.
`externalApplicationId`	Required	Your id for this application. Sending it again returns a fresh link and creates nothing.
`firstName, lastName, email`	Required	The candidate.
`phone, linkedinUrl, location`	Optional	More about the candidate.
`resume`	Optional	Not needed: the candidate is screened on the interview.

Send the interviewUrl to the candidate from your platform. It is personal to them, needs no sign-in and works for 14 days. Alfa sends the candidate nothing itself.
Sending the same externalApplicationId again answers 200 with a fresh link and creates nothing new. Use it to resend an expired link.
interviewUrl is null once the interview is done, or when the candidate does not meet the job's requirements; a not_suitable webhook then follows.

Read about applicant intake for every error and the full field list.

5. Receive the interview

Once the interview is scored, Alfa sends candidate.screened to the client's endpoint, with your externalCandidateId and externalApplicationId so you can match it. The candidate carries:

status (suitable or not_suitable), score from 0 to 100 and summary;
interview.videoUrl, a link to the recording that works for 24 hours;
interview.transcript, turn by turn, and interview.chapters, the recording split into topics, both with times in seconds;
interview.audioOnly and interview.durationSeconds.

Copy the recording to your own storage, or fetch a fresh link when you need one with GET /v1/integration/candidates/{candidateId}/interview-video. Verify every event's signature, answer within 10 seconds and ignore an event id you have already processed. Read about webhooks.

6. Track credit usage

One completed interview uses one credit; a candidate who never starts uses none. Alfa invoices monthly for the credits used, so interviews never stop at a zero balance.

GET /v1/integration/platform/usage: your balance and usage this month, by client.
GET /v1/integration/usage with a client's Alfa-Company-Id: that client's usage, by job, for billing your client.
GET /v1/integration/platform/usage/events/page: every interview that used a credit, with your job and candidate ids.

Read about clients and credits.

Going live

Check each step on the development API with your test key:

Create a test client and set its webhook endpoint; send a test event and verify its signature.
Create an interview job and send an application for yourself.
Open the interview link, take the interview and check that candidate.screened arrives with the recording, transcript and score.
Send the same application again and check that it answers 200 with a fresh link and creates nothing new.
Close the job and check that a new application is refused.
Check that the interview appears in your credit usage.

Then switch to your live key and https://api.welovealfa.com, and create your live clients and their webhook endpoints.