Alfa

Applicant intake

Send an applicant for screening

POST/v1/integration/applications

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

    The 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-Keystring

    A 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 for a different request is a 422.

    at least 1 characters · at most 255 characters

Request body

  • externalJobIdstringrequired

    Your ATS job id. An Alfa job must be linked to it.

    at least 1 characters · at most 200 characters

  • externalCandidateIdstringrequired

    Your candidate id, returned on every webhook for this applicant.

    at least 1 characters · at most 200 characters

  • externalApplicationIdstringrequired

    Your application id. Sending the same one again returns the existing application instead of creating another.

    at least 1 characters · at most 200 characters

  • firstNamestringrequired

    First name.

    at least 1 characters · at most 200 characters

  • lastNamestringrequired

    Last name.

    at least 1 characters · at most 200 characters

  • emailstringrequired

    Email address.

    at most 320 characters · format email

  • phonestring | null

    Phone number.

  • linkedinUrlstring | null

    LinkedIn profile URL.

  • locationstring | null

    Where the applicant is based.

  • appliedAtstring | null

    When they applied in your ATS. Defaults to now.

  • screeningAnswersobject[] | null

    Answers to the job's screening questions (see `screeningQuestions` on the job). Every mandatory question needs one, or the request is 422 `screening_questions_incomplete`.

  • resumeobjectrequired

    The resume file.

    Show fields
    • fileNamestringrequired

      The 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

    • contentBase64stringrequired

      The file, base64 encoded. At most 4 MB once decoded; its content must match `contentType`.

      at least 1 characters · at most 5600000 characters

Response body

  • candidateIdstringrequired

    Alfa's id for the applicant; webhooks and the candidate endpoints use it.

  • jobIdintegerrequired

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

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