Applicant intake
Send an applicant for screening
/v1/integration/applicationsFor platform keys whose ATS receives applicants: sends one applicant and their resume against your ATS job id, and Alfa screens them like any other applicant. On a job that interviews applicants the resume is optional. On that job, or on one that requires the AI Interview, the answer's `interviewUrl` is the applicant's personal AI Interview link for you to send them. Answers 202 with Alfa's candidate id. Sending the same `externalApplicationId` again answers 200 with the existing ids and creates nothing. An ATS job no Alfa job is linked to is 422 `ats_job_not_linked`; a closed or paused Alfa job is 409 `job_not_accepting_applications`. Alfa sends the applicant no emails. Applicants count towards the company's applicant limit. Requires an API key with the `applications:write` scope.
Requires an Alfa API key as a bearer token. How API keys work
Headers
Alfa-Company-IdstringThe Company ID of the company to act for. Required with a platform key, and that company must have authorized your platform; a company key acts for its own company and can leave it out.
Idempotency-KeystringA unique value, such as a UUID, sent unchanged on every retry of one request. A retry after the request succeeded returns the same response, marked `Idempotent-Replayed: true`, without running the operation again. Reusing a key on the same operation with a different path or body is a 422.
at least 1 characters · at most 255 characters
Request body
externalJobIdstringrequiredYour ATS job id. An Alfa job must be linked to it.
at least 1 characters · at most 200 characters
externalCandidateIdstringrequiredYour candidate id, returned on every webhook for this applicant.
at least 1 characters · at most 200 characters
externalApplicationIdstringrequiredYour application id. Sending the same one again returns the existing application instead of creating another.
at least 1 characters · at most 200 characters
firstNamestringrequiredFirst name.
at least 1 characters · at most 200 characters
lastNamestringrequiredLast name.
at least 1 characters · at most 200 characters
emailstringrequiredEmail address.
at most 320 characters · format email
phonestring | nullPhone number.
linkedinUrlstring | nullLinkedIn profile URL.
locationstring | nullWhere the applicant is based.
appliedAtstring | nullWhen they applied in your ATS. Defaults to now.
screeningAnswersobject[] | nullAnswers to the job's screening questions (see `screeningQuestions` on the job). Every mandatory question needs one, or the request is 422 `screening_questions_incomplete`.
resumeobjectThe resume file. Required, except on a job that interviews applicants, where Alfa screens the interview and a resume is optional.
Show fields
fileNamestringrequiredThe file name.
at least 1 characters · at most 255 characters
contentTypestringrequired`application/pdf`, `application/msword`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document` or `text/plain`. Anything else is 422 `unsupported_resume_type`.
at least 1 characters · at most 200 characters
contentBase64stringrequiredThe file, base64 encoded. At most 4 MB once decoded; its content must match `contentType`.
at least 1 characters · at most 5600000 characters
Response body
candidateIdstringrequiredAlfa's id for the applicant; webhooks and the candidate endpoints use it.
jobIdintegerrequiredThe Alfa job the applicant was added to.
status"received" | "existing"required`received`: accepted for screening (202). `existing`: this externalApplicationId was already received, and nothing new was created (200).
interviewUrlstring | nullrequiredOn a job that interviews applicants or requires the AI Interview: the applicant's personal link to their AI Interview, valid for 14 days. Send it to them; sending the same application again returns a fresh link. Null on other jobs, once the interview is done, or when the applicant did not pass the job's requirements (a `not_suitable` webhook follows).
Responses
- 200Success.
- 202Accepted for background processing.
- 400The request is malformed: invalid JSON, an unexpected body or an unknown query parameter. Problem details
- 401The bearer token is missing, expired or invalid. Problem details
- 403The caller may not perform this operation, or has no active organisation. Problem details
- 404The resource does not exist or is not visible to the caller. Problem details
- 409The resource is not in a state that allows this, or a request with the same `Idempotency-Key` is still running. Problem details
- 422The request failed validation; `errors` lists each invalid field. Problem details
- 429Too many requests, or the AI service is busy. Retry after a short wait. Problem details
- 500An unexpected error. Quote the `correlationId` to support. Problem details