Docs

Jobs

Create a job linked to an ATS job

POST/v1/integration/jobs

Creates an Alfa job from one of your ATS's jobs, already linked to it, so no recruiter has to link it in the job form. With `publish: true` the job goes live at once and answers with status `live`, ready for `POST /v1/integration/jobs/{jobId}/sourcing`; publishing uses one of the company's job postings and spends no sourcing credits. Otherwise the job is a draft that a recruiter reviews and publishes in Alfa, or that you publish later with `POST /v1/integration/jobs/{jobId}/publish`. If publishing fails, the draft is kept and the error names its id. The job belongs to the person who created the API key. If you have not sent the ATS job with `PUT /v1/integration/ats-jobs/{externalJobId}` yet, Alfa records it as open with this title; an ATS job already sent is left as it is. Send an `Idempotency-Key` header so that a retry returns the same job instead of creating another. An unrecognised country is 422 `invalid_country`; a company that already uses another ATS integration is 409 `ats_integration_conflict`; a company with no job postings left is 402 `job_quota_exceeded`; a company that uses job slots is 409 `publish_in_alfa`, and its draft waits for a recruiter to publish it in Alfa. Requires an API key with the `jobs: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's own id for the job.

    at least 1 characters · at most 200 characters

  • titlestringrequired

    The job title.

    at least 1 characters · at most 200 characters

  • descriptionstringrequired

    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.

  • publishboolean

    Publish the job straight away, so it is live and ready for sourcing. Defaults to false, which leaves a draft for a recruiter to review and publish in Alfa.

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

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