Docs

Jobs

Publish a linked job

POST/v1/integration/jobs/{jobId}/publish

Publishes a draft Alfa job linked to an ATS job, so it goes live and can source candidates. Publishing uses one of the company's job postings and spends no sourcing credits. A job that is already live answers with the job unchanged, so a retry is safe; a closed or archived job is 409 `job_not_draft`. A job that is not linked, or belongs to another company, is 404 `job_not_found`; a company with no job postings left is 402 `job_quota_exceeded`; a job advert Alfa cannot publish is 422 `invalid_job_advert`; a company that uses job slots, or a job created in Alfa rather than through the API, is 409 `publish_in_alfa`, because a recruiter publishes it in Alfa. The API acts as the person who created the key, so a job that person cannot see in Alfa is 404 `job_not_found`. Requires an API key with the `jobs:write` scope.

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

Path parameters

  • jobIdstringrequired

    Alfa's id for the job.

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.

Response body

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