Docs

Alfa API

Clients and credits

An ATS platform can run its own clients on Alfa without them signing up: create each client company, create AI Interview jobs for it, and send candidates their interview links. Your clients have no Alfa logins, and their interviews use your platform's credits.

These operations need a platform key with the clients:write, jobs:write, applications:write and usage:read scopes. Contact Alfa to set up your platform. For the whole workflow in order, read AI Interviews for your clients.

How it works

  1. Create the clientPOST /v1/integration/platform/clients returns its companyId.
  2. Create an interview jobPUT /v1/integration/ats-jobs/{externalJobId}/interview-job, with the client's Alfa-Company-Id.
  3. Send each candidateApplicant intake answers with their interviewUrl. Send it to them.
  4. Receive the interviewThe candidate.screened webhook carries the score, summary, recording, transcript and chapters.

Creating a client

Name each client once, by your own id. Sending the same externalClientId again returns the client you created before, so the call is safe to repeat. The client is connected to your platform from the start: send its companyId in Alfa-Company-Id on every request for it, including its own webhook endpoint.

Create a client
curl -X POST "https://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","country":"United Kingdom"}'

Creating an interview job

Send the job under your own ATS job id. Alfa creates it live, screening applicants by AI interview only. It is not advertised anywhere: candidates reach it only through the interview links you send. Your description is shown to candidates as written, and Alfa writes the scoring criteria from it, which takes a few seconds. Sending the same ATS job again updates the job, and status: "closed" closes it.

Create an interview job
curl -X PUT "https://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","city":"London","country":"United Kingdom","interviewQuestions":["Do you hold a valid SIA license?"]}'

Interviews take about 4 minutes. Candidates take them on video or audio, as interviewFormat allows, in the job's language.

Credits

Your platform buys credits from Alfa in bulk. One AI Interview uses one credit, counted when the candidate completes it; a candidate who leaves before the interview starts uses none. Alfa invoices monthly for the credits you used, including any beyond those you bought, so interviews never stop at a zero balance.

Your usage this month
curl -X GET "https://api.welovealfa.com/v1/integration/platform/usage" \
  -H "Authorization: Bearer $ALFA_API_KEY"
  • GET /v1/integration/platform/usage: your balance, and the credits you bought and used in a period, by client. The period defaults to the current month in UTC.
  • GET /v1/integration/usage with a client's Alfa-Company-Id: that client's usage, by job.
  • GET /v1/integration/platform/usage/events/page: every interview that used a credit, with your job and candidate ids, for reconciling with your own records.

Errors

  • 403 platform_key_required: a company key called a platform operation.
  • 403 not_a_sub_client: the company in Alfa-Company-Id is not one your platform created.
  • 422 unsupported_country: Alfa does not recognize the client's country.
  • 409 interview_job_in_progress: another request is creating the same interview job. Send the request again in a moment.