Alfa

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. 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.

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, choose Authorize a platform and pick your 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.

Reference

Every operation in the API reference lists the Alfa-Company-Id header. The changelog lists every change.