--- title: "Create a question" method: POST path: "/api/v2/postings/{posting_id}/questions" tags: ["Questions"] --- # Create a question `POST /api/v2/postings/{posting_id}/questions` Creates a new question or criterion for a posting. The ``modality`` field determines the question type. ## Path parameters - `posting_id` string, required ## Headers - `X-API-KEY` string, nullable - `Authorization` string, nullable - `X-Workspace-Id` string, nullable ## Request body - CreateQuestionRequest — 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` 'voice' | 'sms' | 'form' | 'resume_eligibility' | 'resume_scoring' | 'voice_tags', required — Question modality: voice, sms, form, resume_eligibility, resume_scoring, voice_tags. - `text` string, required — The question text, criterion text, or tag name. - `evaluation_criteria` string, nullable — Evaluation criteria. - `score_of_1` string, nullable — Score-1 description. - `score_of_5` string, nullable — Score-5 description. - `score_weight` integer, nullable — Importance weight for scoring (1–10). - `not_scored` boolean, nullable — Ask but don't score. - `question_type` string, nullable — Question format. - `min_follow_ups` integer, nullable — Min follow-ups. - `max_follow_ups` integer, nullable — Max follow-ups. - `additional_instructions` string, nullable — Per-question instructions. - `post_processing_evaluation_criteria` string, nullable — Post-interview evaluation criteria. - `expected_answer` string, nullable — Expected answer (SMS). - `expected_value` integer, nullable — Expected numeric value (SMS). - `is_dealbreaker` boolean, nullable — Dealbreaker flag (SMS). - `answer` unknown - `is_knockout` boolean, nullable — Knockout flag (form). - `dropdown_values` object[], nullable — Dropdown options. - `is_answer_mandated` boolean, nullable — Require answer (form). - `mcq_type` string, nullable — MCQ type (form). - `operator` string, nullable — Validation operator (form). - `file_types` string[], nullable — Allowed file types (form). - `allow_multiple_files` boolean, nullable — Multiple files (form). - `slider_min` number, nullable — Slider min (form). - `slider_max` number, nullable — Slider max (form). - `slider_step` number, nullable — Slider step (form). - `response_format` 'text' | 'freeform' | 'date' | 'number', nullable — Response format for voice_tags: 'text', 'freeform', 'date', or 'number'. - `instructions` string, nullable — Instructions (voice_tags). - `options` string[], nullable — Options (voice_tags). - `structured_config` object, nullable — Advanced structured configuration (voice). Opaque key-value object forwarded to the AI interviewer. ## Response `201` Successful Response - SingleResponseQuestionResponse - `data` QuestionResponse, 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``. - `object` 'question' — Object type identifier. - `id` string, required — Unique question/criterion identifier. - `posting_id` string, required — ID of the posting this question belongs to. - `modality` string, required — Question modality: voice, sms, form, resume_eligibility, resume_scoring, voice_tags. - `text` string, required — The question text, criterion text, or tag name. - `rank` integer, nullable — Display order (1-based). Lower ranks appear first. - `evaluation_criteria` string, nullable — Evaluation criteria for scoring. - `score_of_1` string, nullable — Description of what a score of 1 means. - `score_of_5` string, nullable — Description of what a score of 5 means. - `score_weight` integer, nullable — Importance weight for scoring (1–10). - `not_scored` boolean, nullable — Whether this question is asked but not scored (voice). - `question_type` string, nullable — Question format. For voice: 'open-ended' or 'scored'. Auto-inferred by the backend for SMS ('YES_NO', 'NUMERIC') and form ('dropdown', 'file_upload', 'slider', etc.) modalities. - `min_follow_ups` integer, nullable — Minimum follow-up questions (voice). - `max_follow_ups` integer, nullable — Maximum follow-up questions (voice). - `additional_instructions` string, nullable — Per-question instructions for the AI interviewer. - `post_processing_evaluation_criteria` string, nullable — Evaluation criteria applied post-interview. - `expected_answer` string, nullable — Expected answer text (SMS yes/no). - `expected_value` integer, nullable — Expected numeric value (SMS numeric). - `is_dealbreaker` boolean, nullable — Whether wrong answer disqualifies (SMS). - `answer` unknown - `is_knockout` boolean, nullable — Whether this is a knockout question (form). - `dropdown_values` object[], nullable — Dropdown option list (form). - `is_answer_mandated` boolean, nullable — Whether an answer is required (form). - `mcq_type` string, nullable — Multiple-choice type: 'single' or 'multiple' (form). May be auto-set to 'multiple' by the backend for dropdown questions. - `operator` string, nullable — Validation operator: eq, neq, gt, gte, lt, lte (form). May be auto-set by the backend (e.g. 'minimum' for slider questions). - `file_types` string[], nullable — Allowed file extensions (form file_upload). - `allow_multiple_files` boolean, nullable — Allow multiple file uploads (form). - `slider_min` number, nullable — Minimum slider value (form). - `slider_max` number, nullable — Maximum slider value (form). - `slider_step` number, nullable — Slider step increment (form). - `response_format` 'text' | 'freeform' | 'date' | 'number', nullable — Expected response format for voice_tags: 'text', 'freeform', 'date', or 'number'. - `instructions` string, nullable — Extraction instructions (voice_tags). - `options` string[], nullable — Allowed options (voice_tags). - `structured_config` object, nullable — Advanced structured configuration (voice). Opaque key-value object forwarded to the AI interviewer. - `created_at` number, nullable — Unix timestamp when created. - `updated_at` number, nullable — Unix timestamp when last updated. - `meta` object, nullable — Optional metadata. Shape varies by endpoint. ## Other responses - `401` — Invalid or missing API key. - `404` — Resource not found. - `422` — Validation Error - `429` — Rate limit exceeded. --- [API](https://skmtc.net/heymilo/apis/heymilo-public-api.md) · [All operations](https://skmtc.net/heymilo/apis/heymilo-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/heymilo/heymilo-public-api/revisions/5e07b657706b/schema)