Skip to main content
POST
/
api
/
v2
/
postings
Create an interviewer
curl --request POST \
  --url https://api.heymilo.ai/api/v2/postings \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "title": "<string>",
  "description": "",
  "workflow": [
    {
      "type": "<string>",
      "config": {
        "instructions": "<string>",
        "company_overview": "<string>",
        "job_overview": "<string>",
        "interview_process_overview": "<string>",
        "company_overview_delivery_mode": "exact_delivery",
        "job_overview_delivery_mode": "exact_delivery",
        "interview_process_overview_delivery_mode": "exact_delivery",
        "video": true,
        "voice_id": "voice-1",
        "phone_calls_enabled": true,
        "interview_type": "general",
        "num_questions": 13,
        "min_evaluation_score": 0.5,
        "prompt_version": "v2",
        "is_multilingual": true,
        "cheat_detection_config": {},
        "web_interview_config": {}
      },
      "questions": [
        {
          "modality": "<string>",
          "text": "<string>",
          "evaluation_criteria": "<string>",
          "score_of_1": "<string>",
          "score_of_5": "<string>",
          "question_type": "<string>",
          "not_scored": true,
          "expected_answer": "<string>",
          "expected_value": 123,
          "is_dealbreaker": true,
          "answer": "<unknown>",
          "is_knockout": true,
          "dropdown_values": [
            {}
          ],
          "response_format": "<string>",
          "instructions": "<string>",
          "options": [
            "<string>"
          ],
          "score_weight": 2,
          "min_follow_ups": 2,
          "max_follow_ups": 5,
          "additional_instructions": "<string>",
          "post_processing_evaluation_criteria": "<string>",
          "mcq_type": "<string>",
          "operator": "<string>",
          "file_types": [
            "<string>"
          ],
          "allow_multiple_files": true,
          "slider_min": 123,
          "slider_max": 123,
          "slider_step": 123,
          "is_answer_mandated": true
        }
      ]
    }
  ],
  "interview_template_id": "IT_abc123",
  "name": "senior-swe-backend",
  "language": "en",
  "interviewer_name": "Sarah",
  "instructions": "",
  "company_overview": "",
  "job_overview": "",
  "interview_process_overview": "<string>",
  "company_overview_delivery_mode": "exact_delivery",
  "job_overview_delivery_mode": "exact_delivery",
  "interview_process_overview_delivery_mode": "exact_delivery",
  "phone_number_id": "<string>",
  "sender_email_id": "<string>",
  "email_template_group_id": "<string>",
  "design_template_group_id": "<string>",
  "redirect_url": "<string>",
  "scheduling_url": "<string>",
  "deadline": "2025-03-15T00:00:00Z",
  "allow_sms_comms": true,
  "max_retakes": 2,
  "retake_cooldown_days": 1,
  "email_report_to_candidate": true,
  "metadata": {
    "external_id": "ats_12345",
    "source": "workday"
  }
}
'
{
  "data": {
    "id": "<string>",
    "status": "<string>",
    "urls": {
      "candidate_url": "https://candidates.heymilo.io/acme/senior-engineer",
      "ingestion_url_key": "ibURejyPMSlw6de0OZUdoxyoXTgWO78ey2NUo96EOG1gY",
      "review_url": "https://admin.heymilo.ai/w/ABC123/lab2/POST_ID/1-details"
    },
    "created_at": 123,
    "object": "posting",
    "posting": {
      "id": "<string>",
      "company_id": "<string>",
      "title": "<string>",
      "description": "<string>",
      "status": "<string>",
      "finalized": true,
      "archived": true,
      "test_posting": true,
      "object": "posting",
      "name": "senior-software-engineer",
      "language": "en",
      "interviewer_name": "Sarah",
      "workflow": [
        {
          "type": "<string>",
          "order": 123,
          "id": "agent_vi_001",
          "config": {}
        }
      ],
      "urls": {
        "candidate_url": "https://candidates.heymilo.io/acme/senior-engineer",
        "ingestion_url_key": "ibURejyPMSlw6de0OZUdoxyoXTgWO78ey2NUo96EOG1gY",
        "review_url": "https://admin.heymilo.ai/w/ABC123/lab2/POST_ID/1-details"
      },
      "deadline": 1775174400,
      "redirect_url": "https://acme.com/thank-you",
      "scheduling_url": "https://cal.com/acme/interview",
      "max_retakes": 1,
      "allow_sms_comms": false,
      "instructions": "<string>",
      "company_overview": "<string>",
      "job_overview": "<string>",
      "interview_process_overview": "<string>",
      "company_overview_delivery_mode": "<string>",
      "job_overview_delivery_mode": "<string>",
      "interview_process_overview_delivery_mode": "<string>",
      "phone_number_id": "<string>",
      "sender_email_id": "<string>",
      "email_template_group_id": "<string>",
      "design_template_group_id": "<string>",
      "retake_cooldown_days": 123,
      "email_report_to_candidate": false,
      "ats_metadata": {
        "ats_job_id": "WK-12345",
        "ats_name": "workable",
        "source": "job_sync"
      },
      "metadata": {
        "external_id": "ats_12345",
        "source": "workday"
      },
      "created_at": 1739612400,
      "updated_at": 1739617200
    }
  },
  "meta": {}
}

Documentation Index

Fetch the complete documentation index at: https://docs.heymilo.ai/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
X-API-KEY
string
header
required

API key for authentication. Pass your key in the X-API-KEY header.

Headers

​
X-API-KEY
string
required

Body

application/json
​
title
string
required

Job posting title

Required string length: 3 - 200
Example:

"Senior Software Engineer"

​
description
string
default:""

Job posting description. Used by AI to generate interview questions.

Maximum string length: 50000
​
workflow
(_WebInterviewStep · object | _ConversationalSMSStep · object | _ResumeStep · object | _FormStep · object)[] | null

Ordered list of workflow steps with optional config and questions. Required unless interview_template_id is provided. Mutually exclusive with interview_template_id.

Workflow step for web_interview agent.

​
interview_template_id
string | null

Optional interview template ID to use as the starting point for this posting. When provided, the template's blueprint posting is cloned (workflow, questions, criteria, agent settings, and any linked configurations are copied) and any other fields supplied in this request override the cloned values (title, description, root-level configs, integration IDs, metadata, etc.). Mutually exclusive with workflow: provide one or the other.

Example:

"IT_abc123"

​
name
string | null

Internal posting slug

Example:

"senior-swe-backend"

​
language
string
default:en

Interview language (ISO 639-1)

Example:

"en"

​
interviewer_name
string
default:Sarah

AI interviewer display name

​
instructions
string
default:""

Instructions for the AI interviewer

​
company_overview
string
default:""

Brief overview of the company

​
job_overview
string
default:""

Brief overview of the role

​
interview_process_overview
string | null

Process overview shared with agents.

Maximum string length: 10000
​
company_overview_delivery_mode
enum<string> | null

How the AI interviewer delivers the company overview. 'exact_delivery' (verbatim, default), 'summarized_delivery' (concise candidate-friendly summary), 'reference_only' (used only to answer candidate questions), 'silent_reference' (used internally, never shared with candidate).

Available options:
exact_delivery,
summarized_delivery,
reference_only,
silent_reference
​
job_overview_delivery_mode
enum<string> | null

How the AI interviewer delivers the job overview. Same options as company_overview_delivery_mode.

Available options:
exact_delivery,
summarized_delivery,
reference_only,
silent_reference
​
interview_process_overview_delivery_mode
enum<string> | null

How the AI interviewer delivers the interview process overview. Same options as company_overview_delivery_mode.

Available options:
exact_delivery,
summarized_delivery,
reference_only,
silent_reference
​
phone_number_id
string | null

Phone number ID for SMS and voice agents.

​
sender_email_id
string | null

Sender email ID for candidate communications.

​
email_template_group_id
string | null

Email template group ID for candidate emails.

​
design_template_group_id
string | null

Design template group ID for interview UI branding.

​
redirect_url
string | null

URL to redirect candidates after completing the interview.

​
scheduling_url
string | null

Calendar scheduling URL for shortlisted candidates.

​
deadline
string | null

ISO 8601 deadline for the posting (e.g. '2025-03-15T00:00:00Z'). If omitted or null, defaults to one calendar month after creation.

Example:

"2025-03-15T00:00:00Z"

​
allow_sms_comms
boolean | null

Allow sending SMS invitations to candidates.

​
max_retakes
integer | null

Max retake attempts (0-5).

Required range: 0 <= x <= 5
​
retake_cooldown_days
number | null

Days a candidate must wait between retake attempts.

Required range: x >= 0
​
email_report_to_candidate
boolean | null

Email a performance report link to candidates after completion.

​
metadata
Metadata · object

Set of key-value pairs for storing additional information on the interviewer. Up to 50 keys, each key max 40 chars, each value max 500 chars.

Example:
{
  "external_id": "ats_12345",
  "source": "workday"
}

Response

Successful Response

​
data
CreatePostingResponse · object
required

Response after successfully creating a posting.

​
meta
Meta · object

Optional metadata. Shape varies by endpoint.