Alfa API

Changelog

Additions within /v1, such as new fields, events and endpoints, are not breaking changes, so your integration should ignore fields it does not know. A breaking change ships as /v2 with at least 6 months' notice, announced here.

PSA license number checks in applicant intake

  • POST /v1/integration/applications answers 422 invalid_psa_license_number when the answer to a PSA license number question is not a PSA license number such as EM123456/28.

Sourcing refusals follow account status

  • POST /v1/integration/jobs/{jobId}/sourcing answers 402 payment_required when the company's Alfa account is paused or canceled. Alfa no longer takes payment in the app, so the company asks its account manager to reactivate the account rather than updating a payment method.

No sourcing for canceled subscriptions

  • POST /v1/integration/jobs/{jobId}/sourcing answers 402 payment_required for a company whose Alfa subscription has been canceled, and starts no campaign.

Locked company accounts

  • Every request for a company whose Alfa account is locked answers 403 account_locked.

Extra members on error responses

  • An error response can carry members beyond type, title, status, detail, code, correlationId and errors. Ignore any member you do not know.

Jobs act as the person who created the API key

  • Updating, publishing and closing a job act as the person who created the API key, so a job that person cannot see in Alfa answers 404 job_not_found. Reading and listing jobs are not limited in this way.
  • POST /v1/integration/jobs/{jobId}/publish publishes only drafts created through the API. A draft created in Alfa answers 409 publish_in_alfa, and a recruiter publishes it there.

Agency integrations: job fields, resumes, channels, adverts and contact checks

  • POST /v1/integration/jobs and PATCH /v1/integration/jobs/{jobId} take salary, locations (several advertising places), the Temporary contract type, screeningCriteria (scoring criteria kept separate from the advert), interviewQuestions and requireInterview.
  • Every candidate now carries resume, the resume as structured data, and channel, where the candidate came from.
  • GET /v1/integration/jobs/{jobId}/postings lists each job board advert with its status and link, and counts applicants by channel.
  • The contact check: register an endpoint with PUT /v1/integration/contact-check-endpoint, and Alfa asks it before every outbound approach, failing closed.
  • New webhook event candidate.opted_out, sent when someone Alfa found opts out through Alfa.
  • New guide: Advertise and screen jobs from your CRM.

Change drafts and close jobs through the API

  • PATCH /v1/integration/jobs/{jobId} changes a linked job draft before it is published. A new description or screeningCriteria also rewrites the scoring criteria.
  • A published job cannot be changed, because its advert has already gone out across Alfa’s advertising network: PATCH answers 409 job_not_draft. Close the job and create a new one.
  • POST /v1/integration/jobs/{jobId}/close closes a linked job: it stops taking applications, its job adverts are taken down and any sourcing on it stops. A repeat answers the same.

Publish jobs through the API

  • POST /v1/integration/jobs takes publish: true to put the job live at once, ready for sourcing, with no recruiter step in Alfa.
  • POST /v1/integration/jobs/{jobId}/publish publishes a draft created earlier. A job already live answers unchanged, so a retry is safe.
  • Publishing uses one of the company’s job postings and spends no sourcing credits. New errors job_not_draft, job_quota_exceeded, advert_not_ready and invalid_job_advert.
  • A company that uses job slots gets 409 publish_in_alfa: a recruiter publishes its jobs in Alfa.

Interview links for jobs that require the AI Interview

  • Applicant intake now returns interviewUrl on a job that requires the AI Interview, as well as on a job that interviews applicants.

Sourcing credits go where Alfa chooses

  • POST /v1/integration/jobs/{jobId}/sourcing spends credits on a sourcing campaign. Alfa decides where they go: it can post job ads and search professional profiles, choosing the mix from the kind of role and its advertising locations. Each credit buys seven days of reach and uses one of the company’s sourcing credits, however many channels Alfa uses.
  • GET /v1/integration/jobs/{jobId}/sourcing lists every sourcing campaign on the job, including campaigns that only post job ads, and credits now reports the credits each campaign charged.
  • The outbound-sourcing paths still work as deprecated aliases of the sourcing paths.
  • For a job advertised in several locations, send a multiple of the number of locations.

Create jobs linked to ATS jobs

  • POST /v1/integration/jobs creates an Alfa job draft from an ATS job’s title and description, already linked to its externalJobId, so no recruiter has to link it in the job form. A recruiter reviews and publishes the draft in Alfa.
  • The jobs:write scope is now available to company keys, and the error invalid_country is new.

Outbound sourcing

  • POST /v1/integration/jobs/{jobId}/outbound-sourcing starts an outbound sourcing campaign on a live linked job, using the company’s sourcing credits. Candidates it finds arrive as src_… candidates with status sourced_potential.
  • GET /v1/integration/jobs/{jobId}/outbound-sourcing lists the job’s outbound sourcing campaigns and how many sourced candidates have been reported.
  • New scope sourcing:write, and errors sourcing_disabled, payment_required, job_not_live, insufficient_sourcing_credits, request_id_reused and sourcing_not_started.

The candidate.interview_completed webhook

  • candidate.interview_completed is sent once when a candidate already reported finishes their AI Interview and it is scored, with the recording, transcript, chapters and the updated score and summary.
  • On a job that interviews applicants, candidate.screened still carries the interview, and no separate event is sent.

Webhook alerts for platforms

  • When a webhook endpoint a platform set for a client is turned off after 3 days of failures, Alfa emails the platform’s technical contact, naming the client.
  • The webhooks guide explains how to rotate a signing secret without rejecting events.

Clients, interview jobs and credits for platforms

  • POST /v1/integration/platform/clients creates a client company for your platform, and GET /v1/integration/platform/clients/page lists them.
  • PUT /v1/integration/ats-jobs/{externalJobId}/interview-job creates, updates or closes an AI Interview job for a client.
  • Credit usage: GET /v1/integration/platform/usage, GET /v1/integration/usage and GET /v1/integration/platform/usage/events/page.
  • New scopes clients:write, jobs:write and usage:read, and errors platform_key_required, not_a_sub_client and unsupported_country.

AI Interviews through applicant intake

  • Applicant intake accepts jobs that interview applicants: the resume is optional there, and the response carries the applicant’s interviewUrl.
  • Candidates carry their AI Interview: the recording link, transcript and chapters, in interview.
  • GET /v1/integration/candidates/{candidateId}/interview-video returns a fresh link to the recording.
  • The interview_only_job error is retired; resume_required and interview_not_available are new.

Alfa API v1: API keys, ATS jobs, linked jobs, candidates, webhooks, applicant intake and platform keys

  • API keys, generated in Settings › Developers, with live and test environments, scopes, rotation and expiry.
  • ATS jobs: create and update your jobs so recruiters can link Alfa jobs to them.
  • Linked jobs and candidates, with resumes and polling by update time.
  • Webhooks: candidate.screened, candidate.status_changed and webhook.test, signed, retried for 24 hours, with a delivery log and redelivery.
  • Applicant intake for platform keys.
  • Platform keys, for ATS platforms that serve many client companies.

Start with the Alfa API overview or the API reference.