Alfa API

Platform keys

A platform key lets an ATS platform build one Alfa integration and use it for every client company that also uses Alfa. It calls the same endpoints and receives the same webhooks as a company key; each request names the client company it is for.

Getting a platform key

Alfa issues platform keys to ATS platforms. Contact Alfa to set up your platform. Like any key, a platform key is live or test, has fixed scopes, and is used as a bearer token (authentication).

Naming the client company

Send the client company's Company ID in the Alfa-Company-Id header on every request, except the /v1/integration/platform operations, which act for your platform itself. A Company ID starts org_; the company's admins find it in Alfa, in Settings › Developers, and give it to you when they connect.

A request for one client company
curl -X GET "https://api.welovealfa.com/v1/integration/ats-jobs/page" \
  -H "Authorization: Bearer $ALFA_API_KEY" \
  -H "Alfa-Company-Id: org_2abcDEF123"
  • No header: 400 company_id_required.
  • A company that has not authorized your platform, or has revoked it: 403 company_not_connected.
  • A company that does not have the Alfa API switched on: 403 api_not_enabled.
  • A company whose Alfa account is locked: 403 account_locked.

How a company authorizes your platform

Consent stays with the client company. Ask an org admin at the company to:

  1. Open Settings › Developers in Alfa.
  2. Under Connected platforms, pick your platform and choose Authorize platform.
  3. Send you their Company ID, shown on the same page.

The admin can revoke the authorization on the same page at any time. Revoking immediately cuts your platform's access to that company, and Alfa stops sending you its webhooks. Requests for the company then answer 403 company_not_connected.

Webhooks for each company

A platform key has one webhook endpoint for each connected company. Set it with PUT /v1/integration/webhook-endpoint and that company's Alfa-Company-Id; each endpoint has its own signing secret and delivery log. You can use the same URL for every company: each event names its company in organizationId. Read about webhooks.

Rate limits

A platform key may make 120 requests a minute for each client company and 1,200 a minute in total. Applicant intake allows 60 requests a minute for each company. Over a limit, the API answers 429 rate_limited with Retry-After. Read about rate limits.

Applicant intake

If applicants apply through your ATS, a platform key with the applications:write scope can send them to Alfa for screening. Read about applicant intake.

Running your clients on Alfa

Instead of asking each client to authorize you, your platform can create its clients' companies itself, with their AI Interview jobs, and pay for their interviews with credits. Read about clients and credits.

Reference

Every operation in the API reference that acts for a client company lists the Alfa-Company-Id header. The changelog lists every change.