Skip to main content
POST
/
api
/
v2
/
postings
/
{posting_id}
/
questions
Create a question
curl --request POST \
  --url https://api.heymilo.ai/api/v2/postings/{posting_id}/questions \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "modality": "voice",
  "text": "<string>",
  "evaluation_criteria": "<string>",
  "score_of_1": "<string>",
  "score_of_5": "<string>",
  "score_weight": 5,
  "not_scored": true,
  "question_type": "<string>",
  "min_follow_ups": 1,
  "max_follow_ups": 1,
  "additional_instructions": "<string>",
  "post_processing_evaluation_criteria": "<string>",
  "expected_answer": "<string>",
  "expected_value": 123,
  "is_dealbreaker": true,
  "answer": "<unknown>",
  "is_knockout": true,
  "dropdown_values": [
    {}
  ],
  "is_answer_mandated": true,
  "mcq_type": "<string>",
  "operator": "<string>",
  "file_types": [
    "<string>"
  ],
  "allow_multiple_files": true,
  "slider_min": 123,
  "slider_max": 123,
  "slider_step": 123,
  "response_format": "text",
  "instructions": "<string>",
  "options": [
    "<string>"
  ],
  "structured_config": {}
}
'
{
  "data": {
    "id": "<string>",
    "posting_id": "<string>",
    "modality": "<string>",
    "text": "<string>",
    "object": "question",
    "rank": 1,
    "evaluation_criteria": "<string>",
    "score_of_1": "<string>",
    "score_of_5": "<string>",
    "score_weight": 123,
    "not_scored": true,
    "question_type": "<string>",
    "min_follow_ups": 123,
    "max_follow_ups": 123,
    "additional_instructions": "<string>",
    "post_processing_evaluation_criteria": "<string>",
    "expected_answer": "<string>",
    "expected_value": 123,
    "is_dealbreaker": true,
    "answer": "<unknown>",
    "is_knockout": true,
    "dropdown_values": [
      {}
    ],
    "is_answer_mandated": true,
    "mcq_type": "<string>",
    "operator": "<string>",
    "file_types": [
      "<string>"
    ],
    "allow_multiple_files": true,
    "slider_min": 123,
    "slider_max": 123,
    "slider_step": 123,
    "response_format": "text",
    "instructions": "<string>",
    "options": [
      "<string>"
    ],
    "structured_config": {},
    "created_at": 123,
    "updated_at": 123
  },
  "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

Path Parameters

​
posting_id
string
required

Body

application/json

Request body for creating a new question or criterion.

The modality field determines the question type. Only fields relevant to the chosen modality need to be provided.

​
modality
enum<string>
required

Question modality: voice, sms, form, resume_eligibility, resume_scoring, voice_tags.

Available options:
voice,
sms,
form,
resume_eligibility,
resume_scoring,
voice_tags
Example:

"voice"

​
text
string
required

The question text, criterion text, or tag name.

Example:

"Tell me about a challenging project you led."

​
evaluation_criteria
string | null

Evaluation criteria.

​
score_of_1
string | null

Score-1 description.

​
score_of_5
string | null

Score-5 description.

​
score_weight
integer | null

Importance weight for scoring (1–10).

Required range: 1 <= x <= 10
​
not_scored
boolean | null

Ask but don't score.

​
question_type
string | null

Question format.

​
min_follow_ups
integer | null

Min follow-ups.

Required range: x >= 0
​
max_follow_ups
integer | null

Max follow-ups.

Required range: x >= 0
​
additional_instructions
string | null

Per-question instructions.

​
post_processing_evaluation_criteria
string | null

Post-interview evaluation criteria.

​
expected_answer
string | null

Expected answer (SMS).

​
expected_value
integer | null

Expected numeric value (SMS).

​
is_dealbreaker
boolean | null

Dealbreaker flag (SMS).

​
answer
any | null

Expected answer (form).

​
is_knockout
boolean | null

Knockout flag (form).

​
dropdown_values
Dropdown Values · object[] | null

Dropdown options.

​
is_answer_mandated
boolean | null

Require answer (form).

​
mcq_type
string | null

MCQ type (form).

​
operator
string | null

Validation operator (form).

​
file_types
string[] | null

Allowed file types (form).

​
allow_multiple_files
boolean | null

Multiple files (form).

​
slider_min
number | null

Slider min (form).

​
slider_max
number | null

Slider max (form).

​
slider_step
number | null

Slider step (form).

​
response_format
enum<string> | null

Response format for voice_tags: 'text', 'freeform', 'date', or 'number'.

Available options:
text,
freeform,
date,
number
​
instructions
string | null

Instructions (voice_tags).

​
options
string[] | null

Options (voice_tags).

​
structured_config
Structured Config · object

Advanced structured configuration (voice). Opaque key-value object forwarded to the AI interviewer.

Response

Successful Response

​
data
QuestionResponse · object
required

A question or criterion belonging to a posting.

The modality field indicates the question type (voice, sms, form, resume_eligibility, resume_scoring, voice_tags). Fields that are not applicable to a given modality will be null.

​
meta
Meta · object

Optional metadata. Shape varies by endpoint.