> ## 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. # Create an interviewer > Create a fully-configured interviewer with an agentic workflow. Returns the new posting ID, URLs, and a full posting receipt. **ATS-derived templates use a two-step flow.** When `interview_template_id` references a template whose blueprint is ATS-derived, the new posting is returned in an intermediate stage (`status: "draft"`, `ats_metadata.pending_activation: true`) and does **not** begin ingesting candidates. Transition it to live by calling `POST /postings/{posting_id}/activate`, which finalizes the posting and attaches the ATS mapping in one step. Non-ATS create paths are unchanged. ## OpenAPI ````yaml https://api.heymilo.ai/openapi.json post /api/v2/postings openapi: 3.1.0 info: title: HeyMilo Public API description: >- External developer-facing API for HeyMilo. Create interviewers with agentic workflows, ingest candidates, retrieve interview results, and manage workspace resources. version: 2.0.0 servers: - url: https://api.heymilo.ai description: Production security: - ApiKeyAuth: [] tags: - name: Interviewers description: >- Create, read, update, and manage interviewers. An interviewer (posting) combines job details with an AI agent configuration and agentic workflow. - name: Candidates description: >- Ingest candidates into an interviewer's workflow (sync or async, single or bulk) and list candidates with their progress. - name: Interviews description: >- Retrieve full interview results (scorecard, transcript, resume evaluation) and manage per-interview metadata. - name: Webhooks description: >- Register, list, and manage webhook endpoints that receive real-time event notifications. - name: Voices description: Browse the workspace voice registry for AI interviewer voices. - name: Phone Numbers description: List provisioned phone numbers for SMS and voice agents. - name: Sender Emails description: Manage sender email addresses used for candidate communications. - name: Email Templates description: View email templates configured for candidate outreach. - name: Email Template Groups description: View grouped email template configurations. - name: Design Templates description: View design templates that control the candidate interview UI. - name: Design Template Groups description: View grouped design template configurations. - name: Interview Templates description: >- View interview templates, reusable agent configurations cloned from a blueprint posting (workflow, questions, criteria, agent settings). - name: Domains description: Manage custom domains for white-labelled interview URLs. - name: Questions description: >- Create, read, update, delete, and reorder questions and criteria for an interviewer's workflow. Covers all modalities: voice, sms, form, resume_eligibility, resume_scoring, and voice_tags. - name: Workspaces description: >- List the workspaces accessible to the authenticated caller. API-key callers receive a single entry; OAuth callers receive every workspace they are a member of. paths: /api/v2/postings: post: tags: - Interviewers summary: Create an interviewer description: >- Create a fully-configured interviewer with an agentic workflow. Returns the new posting ID, URLs, and a full posting receipt. **ATS-derived templates use a two-step flow.** When `interview_template_id` references a template whose blueprint is ATS-derived, the new posting is returned in an intermediate stage (`status: "draft"`, `ats_metadata.pending_activation: true`) and does **not** begin ingesting candidates. Transition it to live by calling `POST /postings/{posting_id}/activate`, which finalizes the posting and attaches the ATS mapping in one step. Non-ATS create paths are unchanged. operationId: createPosting parameters: - name: X-API-KEY in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key - name: Authorization in: header required: false schema: anyOf: - type: string - type: 'null' title: Authorization - name: X-Workspace-Id in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Workspace-Id requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePostingRequest' responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/SingleResponse_CreatePostingResponse_' '401': description: Invalid or missing API key. content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' '404': description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '429': description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' components: schemas: CreatePostingRequest: properties: title: type: string maxLength: 200 minLength: 3 title: Title description: Job posting title examples: - Senior Software Engineer description: type: string maxLength: 50000 title: Description description: Job posting description. Used by AI to generate interview questions. default: '' workflow: anyOf: - items: oneOf: - $ref: '#/components/schemas/_WebInterviewStep' - $ref: '#/components/schemas/_ConversationalSMSStep' - $ref: '#/components/schemas/_ResumeStep' - $ref: '#/components/schemas/_FormStep' type: array - type: 'null' title: Workflow description: >- Ordered list of workflow steps with optional config and questions. Required unless ``interview_template_id`` is provided. Mutually exclusive with ``interview_template_id``. interview_template_id: anyOf: - type: string - type: 'null' title: Interview Template Id description: >- 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. examples: - IT_abc123 name: anyOf: - type: string - type: 'null' title: Name description: Internal posting slug examples: - senior-swe-backend language: type: string title: Language description: Interview language (ISO 639-1) default: en examples: - en interviewer_name: type: string title: Interviewer Name description: AI interviewer display name default: Sarah instructions: type: string title: Instructions description: Instructions for the AI interviewer default: '' company_overview: type: string title: Company Overview description: Brief overview of the company default: '' job_overview: type: string title: Job Overview description: Brief overview of the role default: '' interview_process_overview: anyOf: - type: string maxLength: 10000 - type: 'null' title: Interview Process Overview description: Process overview shared with agents. company_overview_delivery_mode: anyOf: - type: string enum: - exact_delivery - summarized_delivery - reference_only - silent_reference - type: 'null' title: Company Overview Delivery Mode description: >- 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). job_overview_delivery_mode: anyOf: - type: string enum: - exact_delivery - summarized_delivery - reference_only - silent_reference - type: 'null' title: Job Overview Delivery Mode description: >- How the AI interviewer delivers the job overview. Same options as company_overview_delivery_mode. interview_process_overview_delivery_mode: anyOf: - type: string enum: - exact_delivery - summarized_delivery - reference_only - silent_reference - type: 'null' title: Interview Process Overview Delivery Mode description: >- How the AI interviewer delivers the interview process overview. Same options as company_overview_delivery_mode. phone_number_id: anyOf: - type: string - type: 'null' title: Phone Number Id description: Phone number ID for SMS and voice agents. sender_email_id: anyOf: - type: string - type: 'null' title: Sender Email Id description: Sender email ID for candidate communications. email_template_group_id: anyOf: - type: string - type: 'null' title: Email Template Group Id description: Email template group ID for candidate emails. design_template_group_id: anyOf: - type: string - type: 'null' title: Design Template Group Id description: Design template group ID for interview UI branding. redirect_url: anyOf: - type: string - type: 'null' title: Redirect Url description: URL to redirect candidates after completing the interview. scheduling_url: anyOf: - type: string - type: 'null' title: Scheduling Url description: Calendar scheduling URL for shortlisted candidates. deadline: anyOf: - type: string - type: 'null' title: Deadline description: >- ISO 8601 deadline for the posting (e.g. '2025-03-15T00:00:00Z'). If omitted or null, defaults to one calendar month after creation. examples: - '2025-03-15T00:00:00Z' allow_sms_comms: anyOf: - type: boolean - type: 'null' title: Allow Sms Comms description: Allow sending SMS invitations to candidates. max_retakes: anyOf: - type: integer maximum: 5 minimum: 0 - type: 'null' title: Max Retakes description: Max retake attempts (0-5). retake_cooldown_days: anyOf: - type: number minimum: 0 - type: 'null' title: Retake Cooldown Days description: Days a candidate must wait between retake attempts. email_report_to_candidate: anyOf: - type: boolean - type: 'null' title: Email Report To Candidate description: Email a performance report link to candidates after completion. metadata: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Metadata description: >- 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. examples: - external_id: ats_12345 source: workday type: object required: - title title: CreatePostingRequest SingleResponse_CreatePostingResponse_: properties: data: $ref: '#/components/schemas/CreatePostingResponse' meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta description: Optional metadata. Shape varies by endpoint. type: object required: - data title: SingleResponse[CreatePostingResponse] APIErrorResponse: properties: error: $ref: '#/components/schemas/APIError' type: object required: - error title: APIErrorResponse HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError _WebInterviewStep: properties: type: type: string const: web_interview title: Type description: Agent type. config: anyOf: - $ref: '#/components/schemas/WebInterviewConfig' - type: 'null' description: Web interview agent configuration. questions: anyOf: - items: $ref: '#/components/schemas/CreateQuestion' type: array - type: 'null' title: Questions description: Questions for this step. If omitted, AI auto-generates. type: object required: - type title: _WebInterviewStep description: Workflow step for web_interview agent. _ConversationalSMSStep: properties: type: type: string const: conversational_sms title: Type description: Agent type. config: anyOf: - $ref: '#/components/schemas/ConversationalSMSConfig' - type: 'null' description: SMS screening agent configuration. questions: anyOf: - items: $ref: '#/components/schemas/CreateQuestion' type: array - type: 'null' title: Questions description: Criteria for this step. If omitted, AI auto-generates. type: object required: - type title: _ConversationalSMSStep description: Workflow step for conversational_sms agent. _ResumeStep: properties: type: type: string const: resume title: Type description: Agent type. config: anyOf: - $ref: '#/components/schemas/ResumeConfig' - type: 'null' description: Resume screening agent configuration. questions: anyOf: - items: $ref: '#/components/schemas/CreateQuestion' type: array - type: 'null' title: Questions description: Criteria for this step. If omitted, AI auto-generates. type: object required: - type title: _ResumeStep description: Workflow step for resume screening agent. _FormStep: properties: type: type: string const: form title: Type description: Agent type. config: anyOf: - $ref: '#/components/schemas/FormConfig' - type: 'null' description: Form screening agent configuration. questions: anyOf: - items: $ref: '#/components/schemas/CreateQuestion' type: array - type: 'null' title: Questions description: Questions for this step. If omitted, AI auto-generates. type: object required: - type title: _FormStep description: Workflow step for form screening agent. CreatePostingResponse: properties: object: type: string const: posting title: Object description: Object type identifier. default: posting id: type: string title: Id description: Unique posting identifier. examples: - 13D77095 status: type: string title: Status description: Posting status after creation. examples: - active urls: $ref: '#/components/schemas/PostingURLs' description: All URLs associated with this posting. created_at: type: number title: Created At description: Unix timestamp when the posting was created. examples: - 1739612400 posting: anyOf: - $ref: '#/components/schemas/PostingResponse' - type: 'null' description: Full posting resource (receipt pattern). type: object required: - id - status - urls - created_at title: CreatePostingResponse description: Response after successfully creating a posting. APIError: properties: type: type: string title: Type description: Error category examples: - invalid_request_error code: type: string title: Code description: Machine-readable error code examples: - validation_error message: type: string title: Message description: Human-readable summary examples: - The request body failed validation param: anyOf: - type: string - type: 'null' title: Param description: Top-level parameter that caused the error doc_url: anyOf: - type: string - type: 'null' title: Doc Url description: Link to relevant documentation errors: items: $ref: '#/components/schemas/APIErrorDetail' type: array title: Errors description: Detailed per-field validation errors type: object required: - type - code - message title: APIError ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError WebInterviewConfig: properties: instructions: anyOf: - type: string maxLength: 10000 - type: 'null' title: Instructions description: >- Per-step override for AI interviewer instructions. Falls back to the posting-level 'instructions' when omitted. company_overview: anyOf: - type: string maxLength: 10000 - type: 'null' title: Company Overview description: >- Per-step override for company overview. Falls back to the posting-level 'company_overview' when omitted. job_overview: anyOf: - type: string maxLength: 10000 - type: 'null' title: Job Overview description: >- Per-step override for job overview. Falls back to the posting-level 'job_overview' when omitted. interview_process_overview: anyOf: - type: string maxLength: 10000 - type: 'null' title: Interview Process Overview description: >- Per-step override for interview process overview. Falls back to the posting-level 'interview_process_overview' when omitted. company_overview_delivery_mode: anyOf: - type: string enum: - exact_delivery - summarized_delivery - reference_only - silent_reference - type: 'null' title: Company Overview Delivery Mode description: >- Per-step override for how the AI interviewer delivers the company overview. Falls back to the posting-level value when omitted. job_overview_delivery_mode: anyOf: - type: string enum: - exact_delivery - summarized_delivery - reference_only - silent_reference - type: 'null' title: Job Overview Delivery Mode description: >- Per-step override for how the AI interviewer delivers the job overview. Falls back to the posting-level value when omitted. interview_process_overview_delivery_mode: anyOf: - type: string enum: - exact_delivery - summarized_delivery - reference_only - silent_reference - type: 'null' title: Interview Process Overview Delivery Mode description: >- Per-step override for how the AI interviewer delivers the interview process overview. Falls back to the posting-level value when omitted. video: anyOf: - type: boolean - type: 'null' title: Video description: 'Enable video during interview (default: audio-only).' voice_id: anyOf: - type: string - type: 'null' title: Voice Id description: >- Voice ID for AI interviewer. Use GET /api/v2/voices to list available voices. examples: - voice-1 - wrv-abc123 phone_calls_enabled: anyOf: - type: boolean - type: 'null' title: Phone Calls Enabled description: Allow outbound phone call interviews (requires phone_number_id). interview_type: anyOf: - type: string - type: 'null' title: Interview Type description: 'Interview focus: general, technical, cultural, behavioral.' examples: - general - technical num_questions: anyOf: - type: integer maximum: 25 minimum: 1 - type: 'null' title: Num Questions description: Number of questions (ignored if questions provided). min_evaluation_score: anyOf: - type: number maximum: 1 minimum: 0 - type: 'null' title: Min Evaluation Score description: Minimum normalized score (0.0-1.0) to pass this stage. prompt_version: anyOf: - type: string - type: 'null' title: Prompt Version description: 'Prompt version: v1 or v2 (latest).' examples: - v2 is_multilingual: anyOf: - type: boolean - type: 'null' title: Is Multilingual description: Auto-detect candidate language and respond in kind. cheat_detection_config: anyOf: - additionalProperties: true type: object - type: 'null' title: Cheat Detection Config description: >- Cheat detection settings: {enabled: bool, threshold: int 0-100, types: ['tab_switching','ai_scripted_answer','multiple_people','multiple_speakers','phone_detection','unusual_delays','facial_behaviour']} web_interview_config: anyOf: - additionalProperties: true type: object - type: 'null' title: Web Interview Config description: >- Advanced interview UI config: {show_transcript, candidate_presence_enabled, min_duration_seconds, max_duration_seconds, backdrop_image_url, avatar_image_url, intro_message, outro_message, remove_heymilo_branding} type: object title: WebInterviewConfig description: Config for the web_interview agent. CreateQuestion: properties: modality: type: string title: Modality description: >- Question modality: voice, resume_eligibility, resume_scoring, form, sms, voice_tags. text: type: string title: Text description: Question text or criterion text. evaluation_criteria: anyOf: - type: string - type: 'null' title: Evaluation Criteria description: How to evaluate (voice, resume_scoring). score_of_1: anyOf: - type: string - type: 'null' title: Score Of 1 description: Score-1 description (voice, resume_scoring). score_of_5: anyOf: - type: string - type: 'null' title: Score Of 5 description: Score-5 description (voice, resume_scoring). question_type: anyOf: - type: string - type: 'null' title: Question Type description: 'Format: open-ended|scored, textarea|dropdown, YES_NO|NUMERIC.' not_scored: anyOf: - type: boolean - type: 'null' title: Not Scored description: Ask but don't score (voice). expected_answer: anyOf: - type: string - type: 'null' title: Expected Answer description: Expected answer (sms). expected_value: anyOf: - type: integer - type: 'null' title: Expected Value description: Expected numeric value (sms). is_dealbreaker: anyOf: - type: boolean - type: 'null' title: Is Dealbreaker description: Disqualify on wrong answer (sms). answer: anyOf: - {} - type: 'null' title: Answer description: Expected answer (form knockout). is_knockout: anyOf: - type: boolean - type: 'null' title: Is Knockout description: Knockout question (form). dropdown_values: anyOf: - items: additionalProperties: type: string type: object type: array - type: 'null' title: Dropdown Values description: Dropdown options (form). response_format: anyOf: - type: string - type: 'null' title: Response Format description: 'Response format: text|number|date|freeform (voice_tags).' instructions: anyOf: - type: string - type: 'null' title: Instructions description: Extraction instructions (voice_tags). options: anyOf: - items: type: string type: array - type: 'null' title: Options description: Allowed options (voice_tags). score_weight: anyOf: - type: integer maximum: 5 minimum: 0 - type: 'null' title: Score Weight description: >- Importance weighting for this question's score (0-5). Higher = more important. Must be a whole number. Applies to voice, sms, resume_eligibility, resume_scoring. min_follow_ups: anyOf: - type: integer maximum: 5 minimum: 0 - type: 'null' title: Min Follow Ups description: Minimum follow-up questions the AI must ask (voice only). max_follow_ups: anyOf: - type: integer maximum: 10 minimum: 0 - type: 'null' title: Max Follow Ups description: Maximum follow-up questions the AI may ask (voice only). additional_instructions: anyOf: - type: string maxLength: 5000 - type: 'null' title: Additional Instructions description: Per-question instructions for the AI interviewer (voice only). post_processing_evaluation_criteria: anyOf: - type: string maxLength: 5000 - type: 'null' title: Post Processing Evaluation Criteria description: >- Evaluation criteria applied against the full transcript after the interview (voice only). mcq_type: anyOf: - type: string - type: 'null' title: Mcq Type description: 'Multiple-choice type: single or multiple (form only).' operator: anyOf: - type: string - type: 'null' title: Operator description: >- Validation operator for number/date questions: eq, neq, gt, gte, lt, lte (form only). file_types: anyOf: - items: type: string type: array - type: 'null' title: File Types description: Allowed file extensions for file_upload questions (form only). allow_multiple_files: anyOf: - type: boolean - type: 'null' title: Allow Multiple Files description: Allow uploading multiple files (form only). slider_min: anyOf: - type: number - type: 'null' title: Slider Min description: Minimum value for slider questions (form only). slider_max: anyOf: - type: number - type: 'null' title: Slider Max description: Maximum value for slider questions (form only). slider_step: anyOf: - type: number - type: 'null' title: Slider Step description: Step increment for slider questions (form only). is_answer_mandated: anyOf: - type: boolean - type: 'null' title: Is Answer Mandated description: Require an answer to this question (form only). type: object required: - modality - text title: CreateQuestion description: A question or criterion for a workflow step. ConversationalSMSConfig: properties: instructions: anyOf: - type: string maxLength: 10000 - type: 'null' title: Instructions description: >- Per-step override for AI interviewer instructions. Falls back to the posting-level 'instructions' when omitted. company_overview: anyOf: - type: string maxLength: 10000 - type: 'null' title: Company Overview description: >- Per-step override for company overview. Falls back to the posting-level 'company_overview' when omitted. job_overview: anyOf: - type: string maxLength: 10000 - type: 'null' title: Job Overview description: >- Per-step override for job overview. Falls back to the posting-level 'job_overview' when omitted. interview_process_overview: anyOf: - type: string maxLength: 10000 - type: 'null' title: Interview Process Overview description: >- Per-step override for interview process overview. Falls back to the posting-level 'interview_process_overview' when omitted. company_overview_delivery_mode: anyOf: - type: string enum: - exact_delivery - summarized_delivery - reference_only - silent_reference - type: 'null' title: Company Overview Delivery Mode description: >- Per-step override for how the AI interviewer delivers the company overview. Falls back to the posting-level value when omitted. job_overview_delivery_mode: anyOf: - type: string enum: - exact_delivery - summarized_delivery - reference_only - silent_reference - type: 'null' title: Job Overview Delivery Mode description: >- Per-step override for how the AI interviewer delivers the job overview. Falls back to the posting-level value when omitted. interview_process_overview_delivery_mode: anyOf: - type: string enum: - exact_delivery - summarized_delivery - reference_only - silent_reference - type: 'null' title: Interview Process Overview Delivery Mode description: >- Per-step override for how the AI interviewer delivers the interview process overview. Falls back to the posting-level value when omitted. knockout_enabled: anyOf: - type: boolean - type: 'null' title: Knockout Enabled description: Auto-disqualify candidates who fail dealbreaker criteria. num_questions: anyOf: - type: integer maximum: 10 minimum: 1 - type: 'null' title: Num Questions description: Number of SMS criteria (ignored if criteria provided). intro_message: anyOf: - type: string maxLength: 500 - type: 'null' title: Intro Message description: >- Custom intro message. Supports {{candidate_name}} and {{job_title}} variables. disqualification_message: anyOf: - type: string maxLength: 500 - type: 'null' title: Disqualification Message description: Message sent when candidate fails a dealbreaker. follow_up_message: anyOf: - type: string maxLength: 500 - type: 'null' title: Follow Up Message description: Custom follow-up/nudge message. hop_on_call_message: anyOf: - type: string maxLength: 500 - type: 'null' title: Hop On Call Message description: Message for phone/video call invitation. cooldown_period_hrs: anyOf: - type: integer maximum: 168 minimum: 1 - type: 'null' title: Cooldown Period Hrs description: Hours to wait before sending a follow-up nudge. max_nudge_amount: anyOf: - type: integer maximum: 10 minimum: 0 - type: 'null' title: Max Nudge Amount description: Maximum number of follow-up nudges. blackout_period: anyOf: - additionalProperties: true type: object - type: 'null' title: Blackout Period description: >- No-message window: {enabled: bool, timezone: str (IANA), start_hour: 0-23, end_hour: 1-24} type: object title: ConversationalSMSConfig description: Config for the conversational_sms agent. ResumeConfig: properties: instructions: anyOf: - type: string maxLength: 10000 - type: 'null' title: Instructions description: >- Per-step override for AI interviewer instructions. Falls back to the posting-level 'instructions' when omitted. company_overview: anyOf: - type: string maxLength: 10000 - type: 'null' title: Company Overview description: >- Per-step override for company overview. Falls back to the posting-level 'company_overview' when omitted. job_overview: anyOf: - type: string maxLength: 10000 - type: 'null' title: Job Overview description: >- Per-step override for job overview. Falls back to the posting-level 'job_overview' when omitted. interview_process_overview: anyOf: - type: string maxLength: 10000 - type: 'null' title: Interview Process Overview description: >- Per-step override for interview process overview. Falls back to the posting-level 'interview_process_overview' when omitted. company_overview_delivery_mode: anyOf: - type: string enum: - exact_delivery - summarized_delivery - reference_only - silent_reference - type: 'null' title: Company Overview Delivery Mode description: >- Per-step override for how the AI interviewer delivers the company overview. Falls back to the posting-level value when omitted. job_overview_delivery_mode: anyOf: - type: string enum: - exact_delivery - summarized_delivery - reference_only - silent_reference - type: 'null' title: Job Overview Delivery Mode description: >- Per-step override for how the AI interviewer delivers the job overview. Falls back to the posting-level value when omitted. interview_process_overview_delivery_mode: anyOf: - type: string enum: - exact_delivery - summarized_delivery - reference_only - silent_reference - type: 'null' title: Interview Process Overview Delivery Mode description: >- Per-step override for how the AI interviewer delivers the interview process overview. Falls back to the posting-level value when omitted. knockout_enabled: anyOf: - type: boolean - type: 'null' title: Knockout Enabled description: Auto-reject candidates failing eligibility criteria. min_evaluation_score: anyOf: - type: number maximum: 1 minimum: 0 - type: 'null' title: Min Evaluation Score description: Minimum normalized score on scoring criteria. mandatory: anyOf: - type: boolean - type: 'null' title: Mandatory description: Require resume upload to proceed. num_eligibility_questions: anyOf: - type: integer maximum: 15 minimum: 0 - type: 'null' title: Num Eligibility Questions description: Number of pass/fail eligibility criteria. num_criteria_questions: anyOf: - type: integer maximum: 15 minimum: 0 - type: 'null' title: Num Criteria Questions description: Number of scored criteria. type: object title: ResumeConfig description: Config for the resume screening agent. FormConfig: properties: instructions: anyOf: - type: string maxLength: 10000 - type: 'null' title: Instructions description: >- Per-step override for AI interviewer instructions. Falls back to the posting-level 'instructions' when omitted. company_overview: anyOf: - type: string maxLength: 10000 - type: 'null' title: Company Overview description: >- Per-step override for company overview. Falls back to the posting-level 'company_overview' when omitted. job_overview: anyOf: - type: string maxLength: 10000 - type: 'null' title: Job Overview description: >- Per-step override for job overview. Falls back to the posting-level 'job_overview' when omitted. interview_process_overview: anyOf: - type: string maxLength: 10000 - type: 'null' title: Interview Process Overview description: >- Per-step override for interview process overview. Falls back to the posting-level 'interview_process_overview' when omitted. company_overview_delivery_mode: anyOf: - type: string enum: - exact_delivery - summarized_delivery - reference_only - silent_reference - type: 'null' title: Company Overview Delivery Mode description: >- Per-step override for how the AI interviewer delivers the company overview. Falls back to the posting-level value when omitted. job_overview_delivery_mode: anyOf: - type: string enum: - exact_delivery - summarized_delivery - reference_only - silent_reference - type: 'null' title: Job Overview Delivery Mode description: >- Per-step override for how the AI interviewer delivers the job overview. Falls back to the posting-level value when omitted. interview_process_overview_delivery_mode: anyOf: - type: string enum: - exact_delivery - summarized_delivery - reference_only - silent_reference - type: 'null' title: Interview Process Overview Delivery Mode description: >- Per-step override for how the AI interviewer delivers the interview process overview. Falls back to the posting-level value when omitted. knockout_enabled: anyOf: - type: boolean - type: 'null' title: Knockout Enabled description: Auto-disqualify on knockout question failure. type: object title: FormConfig description: Config for the form screening agent. PostingURLs: properties: candidate_url: anyOf: - type: string - type: 'null' title: Candidate Url description: Candidate-facing interview URL. examples: - https://candidates.heymilo.io/acme/senior-engineer ingestion_url_key: anyOf: - type: string - type: 'null' title: Ingestion Url Key description: >- URL key for candidate ingestion. Use with POST /intake/v1/candidate/{key}. examples: - ibURejyPMSlw6de0OZUdoxyoXTgWO78ey2NUo96EOG1gY review_url: anyOf: - type: string - type: 'null' title: Review Url description: Admin dashboard review URL. examples: - https://admin.heymilo.ai/w/ABC123/lab2/POST_ID/1-details type: object title: PostingURLs description: All URLs associated with a posting. PostingResponse: properties: object: type: string const: posting title: Object description: Object type identifier. default: posting id: type: string title: Id description: Unique posting identifier. examples: - 13D77095 company_id: type: string title: Company Id description: ID of the company that owns this posting. examples: - comp_abc123 title: type: string title: Title description: Job title displayed to candidates. examples: - Senior Software Engineer name: anyOf: - type: string - type: 'null' title: Name description: URL-friendly slug for the posting. examples: - senior-software-engineer description: type: string title: Description description: Full job description text. examples: - We are looking for a senior software engineer... language: anyOf: - type: string - type: 'null' title: Language description: BCP-47 language code. default: en examples: - en - es interviewer_name: anyOf: - type: string - type: 'null' title: Interviewer Name description: Display name of the AI interviewer. examples: - Sarah status: type: string title: Status description: 'Posting status: ''draft'', ''active'', ''expired'', ''archived''.' examples: - active finalized: type: boolean title: Finalized description: Whether the posting has been finalized/activated. examples: - true archived: type: boolean title: Archived description: Whether the posting is archived. examples: - false test_posting: type: boolean title: Test Posting description: Whether this is a test posting. examples: - false workflow: items: $ref: '#/components/schemas/WorkflowStep' type: array title: Workflow description: Ordered list of agentic workflow steps. urls: anyOf: - $ref: '#/components/schemas/PostingURLs' - type: 'null' description: All URLs associated with this posting. deadline: anyOf: - type: number - type: 'null' title: Deadline description: Unix timestamp deadline for the posting. examples: - 1775174400 redirect_url: anyOf: - type: string - type: 'null' title: Redirect Url description: URL candidates are redirected to after completing the interview. examples: - https://acme.com/thank-you scheduling_url: anyOf: - type: string - type: 'null' title: Scheduling Url description: Calendar scheduling URL for shortlisted candidates. examples: - https://cal.com/acme/interview max_retakes: anyOf: - type: integer - type: 'null' title: Max Retakes description: Maximum number of interview retakes allowed. examples: - 1 allow_sms_comms: anyOf: - type: boolean - type: 'null' title: Allow Sms Comms description: Whether SMS communications are enabled. default: false instructions: anyOf: - type: string - type: 'null' title: Instructions description: General instructions for the AI interviewer shared with agents. company_overview: anyOf: - type: string - type: 'null' title: Company Overview description: Overview of the company shared with agents. job_overview: anyOf: - type: string - type: 'null' title: Job Overview description: Overview of the job/role shared with agents. interview_process_overview: anyOf: - type: string - type: 'null' title: Interview Process Overview description: Overview of the interview process shared with agents. company_overview_delivery_mode: anyOf: - type: string - type: 'null' title: Company Overview Delivery Mode description: How the AI interviewer delivers the company overview. job_overview_delivery_mode: anyOf: - type: string - type: 'null' title: Job Overview Delivery Mode description: How the AI interviewer delivers the job overview. interview_process_overview_delivery_mode: anyOf: - type: string - type: 'null' title: Interview Process Overview Delivery Mode description: How the AI interviewer delivers the interview process overview. phone_number_id: anyOf: - type: string - type: 'null' title: Phone Number Id description: ID of the phone number used for outbound calls. sender_email_id: anyOf: - type: string - type: 'null' title: Sender Email Id description: ID of the sender email configuration. email_template_group_id: anyOf: - type: string - type: 'null' title: Email Template Group Id description: ID of the email template group. design_template_group_id: anyOf: - type: string - type: 'null' title: Design Template Group Id description: ID of the design template group. retake_cooldown_days: anyOf: - type: number - type: 'null' title: Retake Cooldown Days description: Cooldown period in days before a candidate can retake. email_report_to_candidate: anyOf: - type: boolean - type: 'null' title: Email Report To Candidate description: Whether to email the interview report to the candidate. default: false ats_metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Ats Metadata description: >- ATS integration metadata for postings derived from an ATS (Import-from-ATS flow or `createPosting` with an ATS-derived `interview_template_id`). Null for postings not connected to an ATS. Common fields: - `source` (string): how the posting was created, e.g. `job_sync`. - `ats_name` (string): identifier of the ATS, e.g. `workable`, `bullhorn`. - `ats_job_id` (string): ID of the ATS job that backs this posting. - `ats_job_posting_id` (string, optional): ATS-side job-posting ID when distinct from `ats_job_id`. - `integration_id` (string, optional): heymilo ATS integration ID. - `job_ids` (string[], optional): ATS job IDs included in the mapping config. - `pending_activation` (bool): `true` while the agent is in the intermediate stage created by `createPosting` / `clonePosting` for ATS-derived postings. Candidate ingestion does not begin until the caller transitions out of this stage by calling `POST /postings/{posting_id}/activate`, which finalizes the posting and attaches the ATS mapping in one step. - `mapping_activated_at`, `mapping_activated_by` (read-only): audit fields stamped when the ATS mapping was attached. - `mapping_deactivated_at`, `mapping_deactivated_by` (read-only): audit fields stamped when the ATS mapping was last paused. examples: - ats_job_id: WK-12345 ats_name: workable pending_activation: true source: job_sync - ats_job_id: WK-12345 ats_name: workable mapping_activated_at: '2026-05-21T15:00:00' mapping_activated_by: api_key:abcd1234 pending_activation: false source: job_sync metadata: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Metadata description: >- Set of key-value pairs for storing additional information. Up to 50 keys, each key max 40 chars, each value max 500 chars. examples: - external_id: ats_12345 source: workday created_at: anyOf: - type: number - type: 'null' title: Created At description: Unix timestamp when the posting was created. examples: - 1739612400 updated_at: anyOf: - type: number - type: 'null' title: Updated At description: Unix timestamp when the posting was last updated. examples: - 1739617200 type: object required: - id - company_id - title - description - status - finalized - archived - test_posting title: PostingResponse description: |- A job posting with its full agentic workflow configuration. A posting represents a complete hiring pipeline — it defines the job, the AI agents involved, and how candidates progress through each screening step. APIErrorDetail: properties: code: type: string title: Code description: Machine-readable error code examples: - invalid_param message: type: string title: Message description: Human-readable explanation examples: - title must be between 3 and 200 characters param: anyOf: - type: string - type: 'null' title: Param description: Parameter that caused the error examples: - title type: object required: - code - message title: APIErrorDetail WorkflowStep: properties: id: anyOf: - type: string - type: 'null' title: Id description: Unique identifier for this workflow step. examples: - agent_vi_001 type: type: string title: Type description: 'Agent type: ''web_interview'', ''conversational_sms'', ''resume'', ''form''.' examples: - web_interview order: type: integer title: Order description: Position in the workflow pipeline (1-based). examples: - 1 config: additionalProperties: true type: object title: Config description: >- Agent-specific configuration. Shape varies by type. See GET /api/v2/schemas/agents for details. type: object required: - type - order title: WorkflowStep description: A single step in a posting's agentic workflow. securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-KEY description: API key for authentication. Pass your key in the X-API-KEY header. ````