Alfa API

Advertise and screen jobs from your CRM

For recruitment agencies: your CRM creates a job in Alfa, Alfa advertises it and screens the applicants with the AI Interview, and every applicant comes back to your CRM for your consultants to decide on.

How it works

Before you start

• Ask Alfa to switch the Alfa API on for your company and to set up a test company for you.
• Generate a key in Alfa, in Settings › Developers, with jobs:read, jobs:write, candidates:read and webhooks:manage. Add sourcing:write to start outbound sourcing. Start with a test key on the development API (authentication).
• Set your webhook endpoint and store its signing secret, as in webhooks.

1. Create and publish the job

Send the job once the advert is final in your CRM. Your job reference becomes the externalJobId, so the Alfa job is linked to yours with no step in Alfa. Send publish: true to put it live at once.

# Platform keys only: add -H "Alfa-Company-Id: org_2abcDEF123"
curl -X POST "https://dev-api.welovealfa.com/v1/integration/jobs" \
  -H "Authorization: Bearer $ALFA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"externalJobId":"job_8841","title":"Senior Backend Engineer","description":"We are hiring a Senior Backend Engineer for our London office. You will design and run…"}'

• Send an Idempotency-Key header, so that a retry returns the same job instead of creating a second one.
• Publishing uses one of your company's job postings and spends no sourcing credits.

2. Change or close the job

Once a job is published, its advert goes out across Alfa's advertising network and cannot be changed. Until then, change the draft with PATCH /v1/integration/jobs/{jobId}; a field you leave out keeps its value. Changing a published job answers 409 job_not_draft: close it and create a new one.

# Platform keys only: add -H "Alfa-Company-Id: org_2abcDEF123"
curl -X POST "https://dev-api.welovealfa.com/v1/integration/jobs/9301/close" \
  -H "Authorization: Bearer $ALFA_API_KEY"

Close the job when it is filled or closed in your CRM. It stops taking applications, its adverts are taken down, and any sourcing on it stops. Closing a closed job answers the same, so a retry is safe.

3. Receive every applicant

Alfa sends a candidate.screened event for every applicant, suitable or not, and a candidate.status_changed event for each later change. Each event carries:

• status, Alfa's recommendation: suitable, not_suitable or shortlisted. Your consultants make the decision.
• channel, where the applicant came from, such as linkedin, indeed, totaljobs, cv_library, alfa_network or direct.
• resume, the resume as structured data (experience, education, skills, qualifications and languages), and resumeUrl, the resume file.
• interview, the AI Interview transcript, chapters and recording link.

Download the resume and recording when the event arrives: their links work for 24 hours. GET /v1/integration/candidates/{candidateId}/resume and /interview-video return fresh ones. If you miss an event, find it in the delivery log and send it again with POST /v1/integration/webhook-deliveries/{deliveryId}/redeliver.

4. Report on adverts and sources

GET /v1/integration/jobs/{jobId}/postings lists each job board advert with its status and public link, and how many applicants each channel has produced.

# Platform keys only: add -H "Alfa-Company-Id: org_2abcDEF123"
curl -X GET "https://dev-api.welovealfa.com/v1/integration/jobs/9301/postings" \
  -H "Authorization: Bearer $ALFA_API_KEY"

5. Check contacts before outbound sourcing

Before Alfa approaches anyone it found for one of your jobs, it can ask your CRM whether the person may be contacted. Register an HTTPS endpoint with PUT /v1/integration/contact-check-endpoint and store the signing secret. Alfa then sends a signed contact.check request with the person's email, phone and LinkedIn URL at the moment of each approach, and your endpoint answers contactable: true or false for each ref.

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

• The check fails closed. If your endpoint cannot be reached within 5 seconds, answers with an error, or gives no clear answer for the person, Alfa does not approach them. Alfa asks again at the next approach and never reuses an earlier answer.
• POST /v1/integration/contact-check-endpoint/test sends a sample person and reports whether your answer was usable.
• When someone Alfa found opts out through Alfa, for example by replying to unsubscribe, Alfa sends a candidate.opted_out event to your webhook endpoint so you can record it in your CRM.
• Start sourcing on a live job with POST /v1/integration/jobs/{jobId}/sourcing and a key with sourcing:write. People Alfa finds arrive with channel sourced.

Going live

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

1. Create a job with a test key, publish it, and read it back with GET /v1/integration/jobs/{jobId}.
2. Set a webhook endpoint, send a test event and verify its signature.
3. Apply to the job as a test candidate, and check that candidate.screened creates the applicant in your CRM with the resume, interview and channel stored.
4. Change a draft, then check that changing a published job answers 409 job_not_draft.
5. Close the job, and check that GET /v1/integration/jobs/{jobId}/postings shows its adverts closed.
6. Before sourcing, set a contact check endpoint and check that the test request is answered correctly.

Then generate a live key and set the webhook endpoint on the production API.

Reference

The API reference lists every field, and the errors page lists every error code.