Create Job

Starts asynchronous creation of a new job (interviewer) from a job description. Returns immediately with the deterministic Alex interviewerId that the job will be assigned once generation completes. Job generation runs in the background; poll GET /interviewers to detect when the job is available.

POST /createJob

cURL

cURL

curl --request POST \
  --url https://api.alex.com/v1/api/createJob \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data @- <<EOF
{
  "externalJobId": "REQ-12345",
  "jobDescription": "We are looking for a senior backend engineer with experience building distributed systems...",
  "jobTitle": "Senior Backend Engineer",
  "externalJobTitle": "Backend Engineer, Platform",
  "additionalQuestions": [
    "What is your expected start date?"
  ],
  "structuredAdditionalQuestions": [
    {
      "question": "Are you authorized to work in the United States?",
      "answers": [
        "Yes",
        "No"
      ],
      "tagName": "Work Authorization",
      "tagInstructions": "Set to 'Yes' if the candidate confirms US work authorization, otherwise 'No'."
    }
  ],
  "intelligentlyOrderQuestions": false,
  "additionalGenerationContext": "Emphasize systems-design experience over framework specifics.",
  "active": true
}
EOF

200

{
  "success": true,
  "message": "Job generation initiated.",
  "payload": "acme-REQ-12345"
}

Authorizations

X-API-Key · string · header · required

Body

application/json

externalJobId · string · required

Your ATS-side identifier for the job. Must be unique within your company; subsequent calls with the same value will return a 400.

Example:

"REQ-12345"

jobDescription · string · required

Full job description text. Used to generate the interview's questions, skills, and evaluation criteria.

Example:

"We are looking for a senior backend engineer with experience building distributed systems..."

jobTitle · string

The job's title. When omitted or blank, a title is inferred from jobDescription. Supplying it also sharpens the generated questions and evaluation criteria.

Example:

"Senior Backend Engineer"

externalJobTitle · string

The candidate-facing job title, when it should differ from jobTitle. When omitted or blank, it mirrors jobTitle (or the inferred title).

Example:

"Backend Engineer, Platform"

additionalQuestions · string[]

Optional free-text questions to append to the generated interview.

Example:

["What is your expected start date?"]

structuredAdditionalQuestions · object[]

Optional structured questions with answer choices and/or tagging instructions. Use this instead of additionalQuestions when you need constrained-answer questions or report tags.

Show child attributes

intelligentlyOrderQuestions · boolean

When true, additional questions are reordered to flow naturally with the generated interview script. Defaults to false.

Example:

false

additionalGenerationContext · string

Optional free-text guidance to bias question generation (e.g. seniority signals, must-have skills).

Example:

"Emphasize systems-design experience over framework specifics."

active · boolean

Whether the job is created active (true) or inactive (false). When omitted, the company's default job status is used.

Example:

true

Response

200

application/json

Job generation initiated

success · boolean · required

Example:

true

message · string · required

Example:

"Job generation initiated."

payload · string · required

The deterministic Alex interviewerId the job will be assigned once generation completes. Built from your company slug and externalJobId. Use this with /inviteCandidate (as interviewerId) or poll /interviewers to detect when the job is ready.

Example:

"acme-REQ-12345"