Docs

Jobs

Change a linked job draft

PATCH/v1/integration/jobs/{jobId}

Changes a draft Alfa job linked to an ATS job, before it is published. A field you leave out keeps its value. A new `description` or `screeningCriteria` also rewrites the scoring criteria Alfa writes from it; if the job's criteria came from `screeningCriteria`, send it again with a new description to keep them. Once a job is published its advert has gone out across Alfa's advertising network and cannot be changed: a published job is 409 `job_not_draft`, so close it with `POST /v1/integration/jobs/{jobId}/close` and create a new one. A job that is not linked, or belongs to another company, is 404 `job_not_found`; an unrecognised country is 422 `invalid_country`. 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.

Request body

  • titlestring

    The job title.

    at least 1 characters · at most 200 characters

  • descriptionstring

    The job description. It becomes the advert as written. Unless you send `screeningCriteria`, Alfa also writes the scoring criteria from it. Markdown is allowed.

    at least 50 characters · at most 20000 characters

  • screeningCriteriastring

    What Alfa screens candidates against, kept separate from the advert. Alfa writes the scoring criteria from this text instead of the description, and it is never published.

    at least 20 characters · at most 10000 characters

  • citystring | null

    Where the job is. Use `locations` instead to advertise in more than one place.

  • countrystring | null

    The country of the job, by English name or ISO code. Defaults to the company's country.

  • locationsobject[]

    Every place to advertise the job, in place of `city` and `country`. The first is where the job is based. Each place uses its own share of sourcing credits.

    at least 1 items · at most 10 items

    Show fields
    • citystring | null

      A city, town or county. Leave it out to advertise across the whole country.

    • countrystringrequired

      The country, by English name or ISO code.

      at least 1 characters · at most 80 characters

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

    Defaults to On-site.

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

    Defaults to Permanent.

  • salaryobject

    The pay for the job.

    Show fields
    • minnumberrequired

      The lowest pay offered.

      minimum 0

    • maxnumberrequired

      The highest pay offered.

      minimum 0

    • currencystringrequired

      The currency, as an ISO 4217 code.

    • period"year" | "month" | "day" | "hour"required

      What the figures are paid per.

    • showOnAdvertboolean

      Whether the advert shows the salary. Defaults to true.

  • interviewQuestionsstring[]

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

    at most 10 items

  • requireInterviewboolean

    Whether applicants must take the AI Interview. They cannot skip it, and anyone who has not completed it is marked not suitable. Defaults to false.

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