Docs

Interview jobs

Create or update an interview job

PUT/v1/integration/ats-jobs/{externalJobId}/interview-job

Creates the Alfa job behind one of your ATS jobs, for a client your platform created: live at once, screening applicants by AI Interview only, and unlisted (no sourcing or job boards). Your description is shown to candidates as written, and Alfa writes the scoring criteria from it. Send applicants with applicant intake to get their interview links. Sending the same ATS job again updates the job; `status: closed` closes it. Answers 201 when it creates the job and 200 otherwise. A company your platform did not create is 403 `not_a_sub_client`. Requires an API key with the `jobs:write` scope.

Requires an Alfa API key as a bearer token. How API keys work

Path parameters

  • externalJobIdstringrequired

    Your ATS's own id for the job.

    at least 1 characters · at most 200 characters

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.

Request body

  • titlestringrequired

    The job title.

    at least 1 characters · at most 200 characters

  • descriptionstringrequired

    The job description, shown to candidates as written and used for the interview. Markdown is allowed.

    at least 50 characters · at most 20000 characters

  • status"open" | "closed"required

    `open` creates or updates the job. `closed` closes it: applicant intake then refuses new applicants.

  • citystring | null

    Where the job is.

  • countrystring | null

    The country of the job.

  • workSetup"Remote" | "Hybrid" | "On-site"

    Defaults to On-site.

  • contractType"Permanent" | "Contract" | "Temporary"

    Defaults to Permanent.

  • allowInternationalboolean

    Whether applicants based outside the job’s country can pass. Defaults to true.

  • language"en-US" | "en-GB" | "en-CA" | "en-AU" | "en-IN" | "ar" | "bg" | "zh" | "hr" | "cs" | "da" | "nl" | "fi" | "fr" | "de" | "el" | "hi" | "hu" | "id" | "it" | "ja" | "ko" | "ms" | "pl" | "pt" | "ro" | "ru" | "sk" | "es" | "sv" | "ta" | "tr" | "vi" | "bn" | "ka" | "gu" | "he" | "kn" | "ml" | "mr" | "no" | "pa" | "tl" | "te" | "th" | "uk"

    The interview language. Defaults to `en-GB`.

  • interviewFormat"both" | "video" | "audio"

    How candidates may take the interview: video, audio only, or their choice (`both`, the default).

  • interviewQuestionsstring[]

    Questions the AI interviewer asks word for word, before it asks about the role’s requirements.

    at most 10 items

Response body

  • externalJobIdstringrequired

    Your ATS job id.

  • jobobject | nullrequired

    The Alfa job; null once it is closed.

    Show fields
    • jobIdintegerrequired

      Alfa's id for the job.

    • externalJobIdstringrequired

      The ATS job the Alfa job is linked to.

    • titlestring | nullrequired

      The Alfa job title.

    • statusstringrequired

      The Alfa job status: `draft`, `live`, `published`, `paused` or `closed`.

    • applyUrlstringrequired

      The public page where candidates apply.

    • interviewsApplicantsbooleanrequired

      Whether the job screens applicants with an AI Interview. Applicant intake then needs no resume and answers with the applicant’s interview link.

    • screeningQuestionsobject[]required

      The job's screening questions. Send answers to them with applicant intake.

      Show fields
      • questionstringrequired

        The question, as `screeningAnswers` must quote it.

      • typestring | nullrequired

        The answer type: `boolean`, `number`, `text` or `choice`.

      • mandatorybooleanrequired

        Whether the job marks the question as required.

Responses

  • 200Success.
  • 201Created.
  • 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
  • 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