# Interviewers

Create, read, update, and manage interviewers. An interviewer (posting) combines job details with an AI agent configuration and agentic workflow.

## List interviewers

> Retrieve a paginated list of interviewers for the authenticated workspace.

```json
{"openapi":"3.1.0","info":{"title":"HeyMilo Public API","version":"2.0.0"},"tags":[{"name":"Interviewers","description":"Create, read, update, and manage interviewers. An interviewer (posting) combines job details with an AI agent configuration and agentic workflow."}],"servers":[{"url":"https://api.heymilo.ai","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY","description":"API key for authentication. Pass your key in the X-API-KEY header."}},"schemas":{"ListResponse_PostingResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/PostingResponse"},"type":"array","title":"Data"},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"type":"object","required":["data","pagination"],"title":"ListResponse[PostingResponse]"},"PostingResponse":{"properties":{"object":{"type":"string","const":"posting","title":"Object","description":"Object type identifier.","default":"posting"},"id":{"type":"string","title":"Id","description":"Unique posting identifier."},"company_id":{"type":"string","title":"Company Id","description":"ID of the company that owns this posting."},"title":{"type":"string","title":"Title","description":"Job title displayed to candidates."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"URL-friendly slug for the posting."},"description":{"type":"string","title":"Description","description":"Full job description text."},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"BCP-47 language code.","default":"en"},"interviewer_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Interviewer Name","description":"Display name of the AI interviewer."},"status":{"type":"string","title":"Status","description":"Posting status: 'draft', 'active', 'expired', 'archived'."},"finalized":{"type":"boolean","title":"Finalized","description":"Whether the posting has been finalized/activated."},"archived":{"type":"boolean","title":"Archived","description":"Whether the posting is archived."},"test_posting":{"type":"boolean","title":"Test Posting","description":"Whether this is a test posting."},"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."},"redirect_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Redirect Url","description":"URL candidates are redirected to after completing the interview."},"scheduling_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scheduling Url","description":"Calendar scheduling URL for shortlisted candidates."},"max_retakes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Retakes","description":"Maximum number of interview retakes allowed."},"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:\n- `source` (string): how the posting was created, e.g. `job_sync`.\n- `ats_name` (string): identifier of the ATS, e.g. `workable`, `bullhorn`.\n- `ats_job_id` (string): ID of the ATS job that backs this posting.\n- `ats_job_posting_id` (string, optional): ATS-side job-posting ID when distinct from `ats_job_id`.\n- `integration_id` (string, optional): heymilo ATS integration ID.\n- `job_ids` (string[], optional): ATS job IDs included in the mapping config.\n- `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.\n- `mapping_activated_at`, `mapping_activated_by` (read-only): audit fields stamped when the ATS mapping was attached.\n- `mapping_deactivated_at`, `mapping_deactivated_by` (read-only): audit fields stamped when the ATS mapping was last paused."},"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."},"created_at":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Created At","description":"Unix timestamp when the posting was created."},"updated_at":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Updated At","description":"Unix timestamp when the posting was last updated."}},"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.\n\nA posting represents a complete hiring pipeline — it defines the\njob, the AI agents involved, and how candidates progress through\neach screening step."},"WorkflowStep":{"properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id","description":"Unique identifier for this workflow step."},"type":{"type":"string","title":"Type","description":"Agent type: 'web_interview', 'conversational_sms', 'resume', 'form'."},"order":{"type":"integer","title":"Order","description":"Position in the workflow pipeline (1-based)."},"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."},"PostingURLs":{"properties":{"candidate_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Candidate Url","description":"Candidate-facing interview URL."},"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}."},"review_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Review Url","description":"Admin dashboard review URL."}},"type":"object","title":"PostingURLs","description":"All URLs associated with a posting."},"PaginationMeta":{"properties":{"has_more":{"type":"boolean","title":"Has More","description":"Whether more results exist beyond this page"},"total_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Count","description":"Total number of results (if available)"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"URL of this resource"}},"type":"object","required":["has_more"],"title":"PaginationMeta"},"APIErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/APIError"}},"type":"object","required":["error"],"title":"APIErrorResponse"},"APIError":{"properties":{"type":{"type":"string","title":"Type","description":"Error category"},"code":{"type":"string","title":"Code","description":"Machine-readable error code"},"message":{"type":"string","title":"Message","description":"Human-readable summary"},"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"},"APIErrorDetail":{"properties":{"code":{"type":"string","title":"Code","description":"Machine-readable error code"},"message":{"type":"string","title":"Message","description":"Human-readable explanation"},"param":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Param","description":"Parameter that caused the error"}},"type":"object","required":["code","message"],"title":"APIErrorDetail"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/api/v2/postings":{"get":{"tags":["Interviewers"],"summary":"List interviewers","description":"Retrieve a paginated list of interviewers for the authenticated workspace.","operationId":"listPostings","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}},{"name":"starting_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Starting After"}},{"name":"title","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Case-insensitive substring filter on the posting title.","title":"Title"},"description":"Case-insensitive substring filter on the posting title."},{"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"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListResponse_PostingResponse_"}}}},"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"}}}}}}}}}
```

## 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.

```json
{"openapi":"3.1.0","info":{"title":"HeyMilo Public API","version":"2.0.0"},"tags":[{"name":"Interviewers","description":"Create, read, update, and manage interviewers. An interviewer (posting) combines job details with an AI agent configuration and agentic workflow."}],"servers":[{"url":"https://api.heymilo.ai","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY","description":"API key for authentication. Pass your key in the X-API-KEY header."}},"schemas":{"CreatePostingRequest":{"properties":{"title":{"type":"string","maxLength":200,"minLength":3,"title":"Title","description":"Job posting title"},"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."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Internal posting slug"},"language":{"type":"string","title":"Language","description":"Interview language (ISO 639-1)","default":"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."},"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."}},"type":"object","required":["title"],"title":"CreatePostingRequest"},"_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."},"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."},"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."},"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)."},"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."},"_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."},"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."},"_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."},"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."},"_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."},"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."},"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]"},"CreatePostingResponse":{"properties":{"object":{"type":"string","const":"posting","title":"Object","description":"Object type identifier.","default":"posting"},"id":{"type":"string","title":"Id","description":"Unique posting identifier."},"status":{"type":"string","title":"Status","description":"Posting status after creation."},"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."},"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."},"PostingURLs":{"properties":{"candidate_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Candidate Url","description":"Candidate-facing interview URL."},"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}."},"review_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Review Url","description":"Admin dashboard review URL."}},"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."},"company_id":{"type":"string","title":"Company Id","description":"ID of the company that owns this posting."},"title":{"type":"string","title":"Title","description":"Job title displayed to candidates."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"URL-friendly slug for the posting."},"description":{"type":"string","title":"Description","description":"Full job description text."},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"BCP-47 language code.","default":"en"},"interviewer_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Interviewer Name","description":"Display name of the AI interviewer."},"status":{"type":"string","title":"Status","description":"Posting status: 'draft', 'active', 'expired', 'archived'."},"finalized":{"type":"boolean","title":"Finalized","description":"Whether the posting has been finalized/activated."},"archived":{"type":"boolean","title":"Archived","description":"Whether the posting is archived."},"test_posting":{"type":"boolean","title":"Test Posting","description":"Whether this is a test posting."},"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."},"redirect_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Redirect Url","description":"URL candidates are redirected to after completing the interview."},"scheduling_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scheduling Url","description":"Calendar scheduling URL for shortlisted candidates."},"max_retakes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Retakes","description":"Maximum number of interview retakes allowed."},"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:\n- `source` (string): how the posting was created, e.g. `job_sync`.\n- `ats_name` (string): identifier of the ATS, e.g. `workable`, `bullhorn`.\n- `ats_job_id` (string): ID of the ATS job that backs this posting.\n- `ats_job_posting_id` (string, optional): ATS-side job-posting ID when distinct from `ats_job_id`.\n- `integration_id` (string, optional): heymilo ATS integration ID.\n- `job_ids` (string[], optional): ATS job IDs included in the mapping config.\n- `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.\n- `mapping_activated_at`, `mapping_activated_by` (read-only): audit fields stamped when the ATS mapping was attached.\n- `mapping_deactivated_at`, `mapping_deactivated_by` (read-only): audit fields stamped when the ATS mapping was last paused."},"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."},"created_at":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Created At","description":"Unix timestamp when the posting was created."},"updated_at":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Updated At","description":"Unix timestamp when the posting was last updated."}},"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.\n\nA posting represents a complete hiring pipeline — it defines the\njob, the AI agents involved, and how candidates progress through\neach screening step."},"WorkflowStep":{"properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id","description":"Unique identifier for this workflow step."},"type":{"type":"string","title":"Type","description":"Agent type: 'web_interview', 'conversational_sms', 'resume', 'form'."},"order":{"type":"integer","title":"Order","description":"Position in the workflow pipeline (1-based)."},"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."},"APIErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/APIError"}},"type":"object","required":["error"],"title":"APIErrorResponse"},"APIError":{"properties":{"type":{"type":"string","title":"Type","description":"Error category"},"code":{"type":"string","title":"Code","description":"Machine-readable error code"},"message":{"type":"string","title":"Message","description":"Human-readable summary"},"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"},"APIErrorDetail":{"properties":{"code":{"type":"string","title":"Code","description":"Machine-readable error code"},"message":{"type":"string","title":"Message","description":"Human-readable explanation"},"param":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Param","description":"Parameter that caused the error"}},"type":"object","required":["code","message"],"title":"APIErrorDetail"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"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.\n\n**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"}}}}}}}}}
```

## Get an interviewer

> Retrieve the full details of a specific interviewer by ID.

```json
{"openapi":"3.1.0","info":{"title":"HeyMilo Public API","version":"2.0.0"},"tags":[{"name":"Interviewers","description":"Create, read, update, and manage interviewers. An interviewer (posting) combines job details with an AI agent configuration and agentic workflow."}],"servers":[{"url":"https://api.heymilo.ai","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY","description":"API key for authentication. Pass your key in the X-API-KEY header."}},"schemas":{"SingleResponse_PostingResponse_":{"properties":{"data":{"$ref":"#/components/schemas/PostingResponse"},"meta":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Meta","description":"Optional metadata. Shape varies by endpoint."}},"type":"object","required":["data"],"title":"SingleResponse[PostingResponse]"},"PostingResponse":{"properties":{"object":{"type":"string","const":"posting","title":"Object","description":"Object type identifier.","default":"posting"},"id":{"type":"string","title":"Id","description":"Unique posting identifier."},"company_id":{"type":"string","title":"Company Id","description":"ID of the company that owns this posting."},"title":{"type":"string","title":"Title","description":"Job title displayed to candidates."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"URL-friendly slug for the posting."},"description":{"type":"string","title":"Description","description":"Full job description text."},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"BCP-47 language code.","default":"en"},"interviewer_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Interviewer Name","description":"Display name of the AI interviewer."},"status":{"type":"string","title":"Status","description":"Posting status: 'draft', 'active', 'expired', 'archived'."},"finalized":{"type":"boolean","title":"Finalized","description":"Whether the posting has been finalized/activated."},"archived":{"type":"boolean","title":"Archived","description":"Whether the posting is archived."},"test_posting":{"type":"boolean","title":"Test Posting","description":"Whether this is a test posting."},"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."},"redirect_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Redirect Url","description":"URL candidates are redirected to after completing the interview."},"scheduling_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scheduling Url","description":"Calendar scheduling URL for shortlisted candidates."},"max_retakes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Retakes","description":"Maximum number of interview retakes allowed."},"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:\n- `source` (string): how the posting was created, e.g. `job_sync`.\n- `ats_name` (string): identifier of the ATS, e.g. `workable`, `bullhorn`.\n- `ats_job_id` (string): ID of the ATS job that backs this posting.\n- `ats_job_posting_id` (string, optional): ATS-side job-posting ID when distinct from `ats_job_id`.\n- `integration_id` (string, optional): heymilo ATS integration ID.\n- `job_ids` (string[], optional): ATS job IDs included in the mapping config.\n- `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.\n- `mapping_activated_at`, `mapping_activated_by` (read-only): audit fields stamped when the ATS mapping was attached.\n- `mapping_deactivated_at`, `mapping_deactivated_by` (read-only): audit fields stamped when the ATS mapping was last paused."},"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."},"created_at":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Created At","description":"Unix timestamp when the posting was created."},"updated_at":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Updated At","description":"Unix timestamp when the posting was last updated."}},"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.\n\nA posting represents a complete hiring pipeline — it defines the\njob, the AI agents involved, and how candidates progress through\neach screening step."},"WorkflowStep":{"properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id","description":"Unique identifier for this workflow step."},"type":{"type":"string","title":"Type","description":"Agent type: 'web_interview', 'conversational_sms', 'resume', 'form'."},"order":{"type":"integer","title":"Order","description":"Position in the workflow pipeline (1-based)."},"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."},"PostingURLs":{"properties":{"candidate_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Candidate Url","description":"Candidate-facing interview URL."},"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}."},"review_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Review Url","description":"Admin dashboard review URL."}},"type":"object","title":"PostingURLs","description":"All URLs associated with a posting."},"APIErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/APIError"}},"type":"object","required":["error"],"title":"APIErrorResponse"},"APIError":{"properties":{"type":{"type":"string","title":"Type","description":"Error category"},"code":{"type":"string","title":"Code","description":"Machine-readable error code"},"message":{"type":"string","title":"Message","description":"Human-readable summary"},"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"},"APIErrorDetail":{"properties":{"code":{"type":"string","title":"Code","description":"Machine-readable error code"},"message":{"type":"string","title":"Message","description":"Human-readable explanation"},"param":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Param","description":"Parameter that caused the error"}},"type":"object","required":["code","message"],"title":"APIErrorDetail"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/api/v2/postings/{posting_id}":{"get":{"tags":["Interviewers"],"summary":"Get an interviewer","description":"Retrieve the full details of a specific interviewer by ID.","operationId":"getPosting","parameters":[{"name":"posting_id","in":"path","required":true,"schema":{"type":"string","title":"Posting Id"}},{"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"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleResponse_PostingResponse_"}}}},"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"}}}}}}}}}
```

## Update an interviewer

> Update fields on an existing interviewer. Only provided fields are modified; omitted fields remain unchanged.

```json
{"openapi":"3.1.0","info":{"title":"HeyMilo Public API","version":"2.0.0"},"tags":[{"name":"Interviewers","description":"Create, read, update, and manage interviewers. An interviewer (posting) combines job details with an AI agent configuration and agentic workflow."}],"servers":[{"url":"https://api.heymilo.ai","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY","description":"API key for authentication. Pass your key in the X-API-KEY header."}},"schemas":{"UpdatePostingRequest":{"properties":{"title":{"anyOf":[{"type":"string","maxLength":200,"minLength":3},{"type":"null"}],"title":"Title","description":"Updated job title."},"description":{"anyOf":[{"type":"string","maxLength":50000,"minLength":10},{"type":"null"}],"title":"Description","description":"Updated job description."},"name":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Name","description":"Updated URL slug."},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"Updated default language (BCP-47)."},"interviewer_name":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Interviewer Name","description":"Updated AI interviewer display name."},"instructions":{"anyOf":[{"type":"string","maxLength":10000},{"type":"null"}],"title":"Instructions","description":"Updated global instructions for the AI interviewer."},"company_overview":{"anyOf":[{"type":"string","maxLength":10000},{"type":"null"}],"title":"Company Overview","description":"Updated company overview."},"job_overview":{"anyOf":[{"type":"string","maxLength":10000},{"type":"null"}],"title":"Job Overview","description":"Updated job overview."},"interview_process_overview":{"anyOf":[{"type":"string","maxLength":10000},{"type":"null"}],"title":"Interview Process Overview","description":"Updated 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":"Updated company overview delivery mode."},"job_overview_delivery_mode":{"anyOf":[{"type":"string","enum":["exact_delivery","summarized_delivery","reference_only","silent_reference"]},{"type":"null"}],"title":"Job Overview Delivery Mode","description":"Updated job 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":"Updated interview process overview delivery mode."},"phone_number_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone Number Id","description":"Updated phone number ID."},"sender_email_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sender Email Id","description":"Updated sender email ID."},"email_template_group_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email Template Group Id","description":"Updated email template group ID."},"design_template_group_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Design Template Group Id","description":"Updated design template group ID."},"redirect_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Redirect Url","description":"Updated post-completion redirect URL."},"scheduling_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scheduling Url","description":"Updated scheduling URL for shortlisted candidates."},"deadline":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deadline","description":"Updated ISO 8601 deadline."},"allow_sms_comms":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Allow Sms Comms","description":"Updated SMS communications flag."},"max_retakes":{"anyOf":[{"type":"integer","maximum":5,"minimum":0},{"type":"null"}],"title":"Max Retakes","description":"Updated max retake attempts (0-5)."},"retake_cooldown_days":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Retake Cooldown Days","description":"Updated retake cooldown in days."},"email_report_to_candidate":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Email Report To Candidate","description":"Updated email report flag."},"metadata":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Metadata","description":"Updated key-value metadata. Replaces existing metadata entirely. Up to 50 keys, each key max 40 chars, each value max 500 chars."}},"type":"object","title":"UpdatePostingRequest","description":"Request body for updating a posting. All fields are optional."},"SingleResponse_PostingResponse_":{"properties":{"data":{"$ref":"#/components/schemas/PostingResponse"},"meta":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Meta","description":"Optional metadata. Shape varies by endpoint."}},"type":"object","required":["data"],"title":"SingleResponse[PostingResponse]"},"PostingResponse":{"properties":{"object":{"type":"string","const":"posting","title":"Object","description":"Object type identifier.","default":"posting"},"id":{"type":"string","title":"Id","description":"Unique posting identifier."},"company_id":{"type":"string","title":"Company Id","description":"ID of the company that owns this posting."},"title":{"type":"string","title":"Title","description":"Job title displayed to candidates."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"URL-friendly slug for the posting."},"description":{"type":"string","title":"Description","description":"Full job description text."},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"BCP-47 language code.","default":"en"},"interviewer_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Interviewer Name","description":"Display name of the AI interviewer."},"status":{"type":"string","title":"Status","description":"Posting status: 'draft', 'active', 'expired', 'archived'."},"finalized":{"type":"boolean","title":"Finalized","description":"Whether the posting has been finalized/activated."},"archived":{"type":"boolean","title":"Archived","description":"Whether the posting is archived."},"test_posting":{"type":"boolean","title":"Test Posting","description":"Whether this is a test posting."},"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."},"redirect_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Redirect Url","description":"URL candidates are redirected to after completing the interview."},"scheduling_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scheduling Url","description":"Calendar scheduling URL for shortlisted candidates."},"max_retakes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Retakes","description":"Maximum number of interview retakes allowed."},"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:\n- `source` (string): how the posting was created, e.g. `job_sync`.\n- `ats_name` (string): identifier of the ATS, e.g. `workable`, `bullhorn`.\n- `ats_job_id` (string): ID of the ATS job that backs this posting.\n- `ats_job_posting_id` (string, optional): ATS-side job-posting ID when distinct from `ats_job_id`.\n- `integration_id` (string, optional): heymilo ATS integration ID.\n- `job_ids` (string[], optional): ATS job IDs included in the mapping config.\n- `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.\n- `mapping_activated_at`, `mapping_activated_by` (read-only): audit fields stamped when the ATS mapping was attached.\n- `mapping_deactivated_at`, `mapping_deactivated_by` (read-only): audit fields stamped when the ATS mapping was last paused."},"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."},"created_at":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Created At","description":"Unix timestamp when the posting was created."},"updated_at":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Updated At","description":"Unix timestamp when the posting was last updated."}},"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.\n\nA posting represents a complete hiring pipeline — it defines the\njob, the AI agents involved, and how candidates progress through\neach screening step."},"WorkflowStep":{"properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id","description":"Unique identifier for this workflow step."},"type":{"type":"string","title":"Type","description":"Agent type: 'web_interview', 'conversational_sms', 'resume', 'form'."},"order":{"type":"integer","title":"Order","description":"Position in the workflow pipeline (1-based)."},"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."},"PostingURLs":{"properties":{"candidate_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Candidate Url","description":"Candidate-facing interview URL."},"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}."},"review_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Review Url","description":"Admin dashboard review URL."}},"type":"object","title":"PostingURLs","description":"All URLs associated with a posting."},"APIErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/APIError"}},"type":"object","required":["error"],"title":"APIErrorResponse"},"APIError":{"properties":{"type":{"type":"string","title":"Type","description":"Error category"},"code":{"type":"string","title":"Code","description":"Machine-readable error code"},"message":{"type":"string","title":"Message","description":"Human-readable summary"},"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"},"APIErrorDetail":{"properties":{"code":{"type":"string","title":"Code","description":"Machine-readable error code"},"message":{"type":"string","title":"Message","description":"Human-readable explanation"},"param":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Param","description":"Parameter that caused the error"}},"type":"object","required":["code","message"],"title":"APIErrorDetail"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/api/v2/postings/{posting_id}":{"patch":{"tags":["Interviewers"],"summary":"Update an interviewer","description":"Update fields on an existing interviewer. Only provided fields are modified; omitted fields remain unchanged.","operationId":"updatePosting","parameters":[{"name":"posting_id","in":"path","required":true,"schema":{"type":"string","title":"Posting Id"}},{"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/UpdatePostingRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleResponse_PostingResponse_"}}}},"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"}}}}}}}}}
```

## Update a workflow step's config

> Partially update one workflow step's config without touching other steps or posting-level fields. \`\`step\_id\`\` is the step's \`\`type\`\` or its 1-based \`\`order\`\`.

```json
{"openapi":"3.1.0","info":{"title":"HeyMilo Public API","version":"2.0.0"},"tags":[{"name":"Interviewers","description":"Create, read, update, and manage interviewers. An interviewer (posting) combines job details with an AI agent configuration and agentic workflow."}],"servers":[{"url":"https://api.heymilo.ai","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY","description":"API key for authentication. Pass your key in the X-API-KEY header."}},"schemas":{"UpdateWorkflowStepRequest":{"properties":{"config":{"additionalProperties":true,"type":"object","title":"Config","description":"Partial step config. Allowed keys depend on the step's agent type (see the matching step config in the create request). Nested objects are replaced as a whole. Unknown keys return 400."}},"type":"object","required":["config"],"title":"UpdateWorkflowStepRequest","description":"Partial update of a workflow step's config."},"SingleResponse_PostingResponse_":{"properties":{"data":{"$ref":"#/components/schemas/PostingResponse"},"meta":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Meta","description":"Optional metadata. Shape varies by endpoint."}},"type":"object","required":["data"],"title":"SingleResponse[PostingResponse]"},"PostingResponse":{"properties":{"object":{"type":"string","const":"posting","title":"Object","description":"Object type identifier.","default":"posting"},"id":{"type":"string","title":"Id","description":"Unique posting identifier."},"company_id":{"type":"string","title":"Company Id","description":"ID of the company that owns this posting."},"title":{"type":"string","title":"Title","description":"Job title displayed to candidates."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"URL-friendly slug for the posting."},"description":{"type":"string","title":"Description","description":"Full job description text."},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"BCP-47 language code.","default":"en"},"interviewer_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Interviewer Name","description":"Display name of the AI interviewer."},"status":{"type":"string","title":"Status","description":"Posting status: 'draft', 'active', 'expired', 'archived'."},"finalized":{"type":"boolean","title":"Finalized","description":"Whether the posting has been finalized/activated."},"archived":{"type":"boolean","title":"Archived","description":"Whether the posting is archived."},"test_posting":{"type":"boolean","title":"Test Posting","description":"Whether this is a test posting."},"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."},"redirect_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Redirect Url","description":"URL candidates are redirected to after completing the interview."},"scheduling_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scheduling Url","description":"Calendar scheduling URL for shortlisted candidates."},"max_retakes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Retakes","description":"Maximum number of interview retakes allowed."},"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:\n- `source` (string): how the posting was created, e.g. `job_sync`.\n- `ats_name` (string): identifier of the ATS, e.g. `workable`, `bullhorn`.\n- `ats_job_id` (string): ID of the ATS job that backs this posting.\n- `ats_job_posting_id` (string, optional): ATS-side job-posting ID when distinct from `ats_job_id`.\n- `integration_id` (string, optional): heymilo ATS integration ID.\n- `job_ids` (string[], optional): ATS job IDs included in the mapping config.\n- `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.\n- `mapping_activated_at`, `mapping_activated_by` (read-only): audit fields stamped when the ATS mapping was attached.\n- `mapping_deactivated_at`, `mapping_deactivated_by` (read-only): audit fields stamped when the ATS mapping was last paused."},"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."},"created_at":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Created At","description":"Unix timestamp when the posting was created."},"updated_at":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Updated At","description":"Unix timestamp when the posting was last updated."}},"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.\n\nA posting represents a complete hiring pipeline — it defines the\njob, the AI agents involved, and how candidates progress through\neach screening step."},"WorkflowStep":{"properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id","description":"Unique identifier for this workflow step."},"type":{"type":"string","title":"Type","description":"Agent type: 'web_interview', 'conversational_sms', 'resume', 'form'."},"order":{"type":"integer","title":"Order","description":"Position in the workflow pipeline (1-based)."},"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."},"PostingURLs":{"properties":{"candidate_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Candidate Url","description":"Candidate-facing interview URL."},"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}."},"review_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Review Url","description":"Admin dashboard review URL."}},"type":"object","title":"PostingURLs","description":"All URLs associated with a posting."},"APIErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/APIError"}},"type":"object","required":["error"],"title":"APIErrorResponse"},"APIError":{"properties":{"type":{"type":"string","title":"Type","description":"Error category"},"code":{"type":"string","title":"Code","description":"Machine-readable error code"},"message":{"type":"string","title":"Message","description":"Human-readable summary"},"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"},"APIErrorDetail":{"properties":{"code":{"type":"string","title":"Code","description":"Machine-readable error code"},"message":{"type":"string","title":"Message","description":"Human-readable explanation"},"param":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Param","description":"Parameter that caused the error"}},"type":"object","required":["code","message"],"title":"APIErrorDetail"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/api/v2/postings/{posting_id}/workflow/{step_id}":{"patch":{"tags":["Interviewers"],"summary":"Update a workflow step's config","description":"Partially update one workflow step's config without touching other steps or posting-level fields. ``step_id`` is the step's ``type`` or its 1-based ``order``.","operationId":"updateInterviewerWorkflowStep","parameters":[{"name":"posting_id","in":"path","required":true,"schema":{"type":"string","title":"Posting Id"}},{"name":"step_id","in":"path","required":true,"schema":{"type":"string","title":"Step Id"}},{"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/UpdateWorkflowStepRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleResponse_PostingResponse_"}}}},"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"}}}}}}}}}
```

## Archive an interviewer

> Archive an interviewer. Archived interviewers stop accepting new candidates.

```json
{"openapi":"3.1.0","info":{"title":"HeyMilo Public API","version":"2.0.0"},"tags":[{"name":"Interviewers","description":"Create, read, update, and manage interviewers. An interviewer (posting) combines job details with an AI agent configuration and agentic workflow."}],"servers":[{"url":"https://api.heymilo.ai","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY","description":"API key for authentication. Pass your key in the X-API-KEY header."}},"schemas":{"SingleResponse_PostingResponse_":{"properties":{"data":{"$ref":"#/components/schemas/PostingResponse"},"meta":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Meta","description":"Optional metadata. Shape varies by endpoint."}},"type":"object","required":["data"],"title":"SingleResponse[PostingResponse]"},"PostingResponse":{"properties":{"object":{"type":"string","const":"posting","title":"Object","description":"Object type identifier.","default":"posting"},"id":{"type":"string","title":"Id","description":"Unique posting identifier."},"company_id":{"type":"string","title":"Company Id","description":"ID of the company that owns this posting."},"title":{"type":"string","title":"Title","description":"Job title displayed to candidates."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"URL-friendly slug for the posting."},"description":{"type":"string","title":"Description","description":"Full job description text."},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"BCP-47 language code.","default":"en"},"interviewer_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Interviewer Name","description":"Display name of the AI interviewer."},"status":{"type":"string","title":"Status","description":"Posting status: 'draft', 'active', 'expired', 'archived'."},"finalized":{"type":"boolean","title":"Finalized","description":"Whether the posting has been finalized/activated."},"archived":{"type":"boolean","title":"Archived","description":"Whether the posting is archived."},"test_posting":{"type":"boolean","title":"Test Posting","description":"Whether this is a test posting."},"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."},"redirect_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Redirect Url","description":"URL candidates are redirected to after completing the interview."},"scheduling_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scheduling Url","description":"Calendar scheduling URL for shortlisted candidates."},"max_retakes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Retakes","description":"Maximum number of interview retakes allowed."},"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:\n- `source` (string): how the posting was created, e.g. `job_sync`.\n- `ats_name` (string): identifier of the ATS, e.g. `workable`, `bullhorn`.\n- `ats_job_id` (string): ID of the ATS job that backs this posting.\n- `ats_job_posting_id` (string, optional): ATS-side job-posting ID when distinct from `ats_job_id`.\n- `integration_id` (string, optional): heymilo ATS integration ID.\n- `job_ids` (string[], optional): ATS job IDs included in the mapping config.\n- `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.\n- `mapping_activated_at`, `mapping_activated_by` (read-only): audit fields stamped when the ATS mapping was attached.\n- `mapping_deactivated_at`, `mapping_deactivated_by` (read-only): audit fields stamped when the ATS mapping was last paused."},"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."},"created_at":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Created At","description":"Unix timestamp when the posting was created."},"updated_at":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Updated At","description":"Unix timestamp when the posting was last updated."}},"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.\n\nA posting represents a complete hiring pipeline — it defines the\njob, the AI agents involved, and how candidates progress through\neach screening step."},"WorkflowStep":{"properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id","description":"Unique identifier for this workflow step."},"type":{"type":"string","title":"Type","description":"Agent type: 'web_interview', 'conversational_sms', 'resume', 'form'."},"order":{"type":"integer","title":"Order","description":"Position in the workflow pipeline (1-based)."},"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."},"PostingURLs":{"properties":{"candidate_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Candidate Url","description":"Candidate-facing interview URL."},"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}."},"review_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Review Url","description":"Admin dashboard review URL."}},"type":"object","title":"PostingURLs","description":"All URLs associated with a posting."},"APIErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/APIError"}},"type":"object","required":["error"],"title":"APIErrorResponse"},"APIError":{"properties":{"type":{"type":"string","title":"Type","description":"Error category"},"code":{"type":"string","title":"Code","description":"Machine-readable error code"},"message":{"type":"string","title":"Message","description":"Human-readable summary"},"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"},"APIErrorDetail":{"properties":{"code":{"type":"string","title":"Code","description":"Machine-readable error code"},"message":{"type":"string","title":"Message","description":"Human-readable explanation"},"param":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Param","description":"Parameter that caused the error"}},"type":"object","required":["code","message"],"title":"APIErrorDetail"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/api/v2/postings/{posting_id}/archive":{"post":{"tags":["Interviewers"],"summary":"Archive an interviewer","description":"Archive an interviewer. Archived interviewers stop accepting new candidates.","operationId":"archivePosting","parameters":[{"name":"posting_id","in":"path","required":true,"schema":{"type":"string","title":"Posting Id"}},{"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"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleResponse_PostingResponse_"}}}},"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"}}}}}}}}}
```

## Activate an interviewer

> Activate an interviewer so it begins accepting candidates. The interviewer must have a valid workflow configuration.\
> \
> For ATS-derived postings still in the \`pending\_activation\` intermediate stage (created via \`createPosting\` with an ATS-derived \`interview\_template\_id\`, or \`clonePosting\` of an ATS-derived posting), this call finalizes the posting \*\*and\*\* attaches the ATS mapping so candidate ingestion from the ATS begins. The two steps run in one call; the ATS attach is idempotent and best-effort, so re-calling activate is safe and a transient ATS integrator hiccup will not block finalize.

```json
{"openapi":"3.1.0","info":{"title":"HeyMilo Public API","version":"2.0.0"},"tags":[{"name":"Interviewers","description":"Create, read, update, and manage interviewers. An interviewer (posting) combines job details with an AI agent configuration and agentic workflow."}],"servers":[{"url":"https://api.heymilo.ai","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY","description":"API key for authentication. Pass your key in the X-API-KEY header."}},"schemas":{"SingleResponse_PostingResponse_":{"properties":{"data":{"$ref":"#/components/schemas/PostingResponse"},"meta":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Meta","description":"Optional metadata. Shape varies by endpoint."}},"type":"object","required":["data"],"title":"SingleResponse[PostingResponse]"},"PostingResponse":{"properties":{"object":{"type":"string","const":"posting","title":"Object","description":"Object type identifier.","default":"posting"},"id":{"type":"string","title":"Id","description":"Unique posting identifier."},"company_id":{"type":"string","title":"Company Id","description":"ID of the company that owns this posting."},"title":{"type":"string","title":"Title","description":"Job title displayed to candidates."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"URL-friendly slug for the posting."},"description":{"type":"string","title":"Description","description":"Full job description text."},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"BCP-47 language code.","default":"en"},"interviewer_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Interviewer Name","description":"Display name of the AI interviewer."},"status":{"type":"string","title":"Status","description":"Posting status: 'draft', 'active', 'expired', 'archived'."},"finalized":{"type":"boolean","title":"Finalized","description":"Whether the posting has been finalized/activated."},"archived":{"type":"boolean","title":"Archived","description":"Whether the posting is archived."},"test_posting":{"type":"boolean","title":"Test Posting","description":"Whether this is a test posting."},"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."},"redirect_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Redirect Url","description":"URL candidates are redirected to after completing the interview."},"scheduling_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scheduling Url","description":"Calendar scheduling URL for shortlisted candidates."},"max_retakes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Retakes","description":"Maximum number of interview retakes allowed."},"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:\n- `source` (string): how the posting was created, e.g. `job_sync`.\n- `ats_name` (string): identifier of the ATS, e.g. `workable`, `bullhorn`.\n- `ats_job_id` (string): ID of the ATS job that backs this posting.\n- `ats_job_posting_id` (string, optional): ATS-side job-posting ID when distinct from `ats_job_id`.\n- `integration_id` (string, optional): heymilo ATS integration ID.\n- `job_ids` (string[], optional): ATS job IDs included in the mapping config.\n- `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.\n- `mapping_activated_at`, `mapping_activated_by` (read-only): audit fields stamped when the ATS mapping was attached.\n- `mapping_deactivated_at`, `mapping_deactivated_by` (read-only): audit fields stamped when the ATS mapping was last paused."},"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."},"created_at":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Created At","description":"Unix timestamp when the posting was created."},"updated_at":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Updated At","description":"Unix timestamp when the posting was last updated."}},"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.\n\nA posting represents a complete hiring pipeline — it defines the\njob, the AI agents involved, and how candidates progress through\neach screening step."},"WorkflowStep":{"properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id","description":"Unique identifier for this workflow step."},"type":{"type":"string","title":"Type","description":"Agent type: 'web_interview', 'conversational_sms', 'resume', 'form'."},"order":{"type":"integer","title":"Order","description":"Position in the workflow pipeline (1-based)."},"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."},"PostingURLs":{"properties":{"candidate_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Candidate Url","description":"Candidate-facing interview URL."},"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}."},"review_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Review Url","description":"Admin dashboard review URL."}},"type":"object","title":"PostingURLs","description":"All URLs associated with a posting."},"APIErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/APIError"}},"type":"object","required":["error"],"title":"APIErrorResponse"},"APIError":{"properties":{"type":{"type":"string","title":"Type","description":"Error category"},"code":{"type":"string","title":"Code","description":"Machine-readable error code"},"message":{"type":"string","title":"Message","description":"Human-readable summary"},"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"},"APIErrorDetail":{"properties":{"code":{"type":"string","title":"Code","description":"Machine-readable error code"},"message":{"type":"string","title":"Message","description":"Human-readable explanation"},"param":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Param","description":"Parameter that caused the error"}},"type":"object","required":["code","message"],"title":"APIErrorDetail"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/api/v2/postings/{posting_id}/activate":{"post":{"tags":["Interviewers"],"summary":"Activate an interviewer","description":"Activate an interviewer so it begins accepting candidates. The interviewer must have a valid workflow configuration.\n\nFor ATS-derived postings still in the `pending_activation` intermediate stage (created via `createPosting` with an ATS-derived `interview_template_id`, or `clonePosting` of an ATS-derived posting), this call finalizes the posting **and** attaches the ATS mapping so candidate ingestion from the ATS begins. The two steps run in one call; the ATS attach is idempotent and best-effort, so re-calling activate is safe and a transient ATS integrator hiccup will not block finalize.","operationId":"activatePosting","parameters":[{"name":"posting_id","in":"path","required":true,"schema":{"type":"string","title":"Posting Id"}},{"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"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleResponse_PostingResponse_"}}}},"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"}}}}}}}}}
```

## Clone an interviewer

> Create a copy of an existing interviewer with its workflow configuration.\
> \
> If the source interviewer is ATS-derived, the clone is returned in the same intermediate stage as a fresh ATS create (\`status: "draft"\`, \`ats\_metadata.pending\_activation: true\`) and must be transitioned to live via \`POST /postings/{posting\_id}/activate\`. Cloning a non-ATS posting is unchanged.

```json
{"openapi":"3.1.0","info":{"title":"HeyMilo Public API","version":"2.0.0"},"tags":[{"name":"Interviewers","description":"Create, read, update, and manage interviewers. An interviewer (posting) combines job details with an AI agent configuration and agentic workflow."}],"servers":[{"url":"https://api.heymilo.ai","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY","description":"API key for authentication. Pass your key in the X-API-KEY header."}},"schemas":{"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]"},"CreatePostingResponse":{"properties":{"object":{"type":"string","const":"posting","title":"Object","description":"Object type identifier.","default":"posting"},"id":{"type":"string","title":"Id","description":"Unique posting identifier."},"status":{"type":"string","title":"Status","description":"Posting status after creation."},"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."},"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."},"PostingURLs":{"properties":{"candidate_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Candidate Url","description":"Candidate-facing interview URL."},"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}."},"review_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Review Url","description":"Admin dashboard review URL."}},"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."},"company_id":{"type":"string","title":"Company Id","description":"ID of the company that owns this posting."},"title":{"type":"string","title":"Title","description":"Job title displayed to candidates."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"URL-friendly slug for the posting."},"description":{"type":"string","title":"Description","description":"Full job description text."},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"BCP-47 language code.","default":"en"},"interviewer_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Interviewer Name","description":"Display name of the AI interviewer."},"status":{"type":"string","title":"Status","description":"Posting status: 'draft', 'active', 'expired', 'archived'."},"finalized":{"type":"boolean","title":"Finalized","description":"Whether the posting has been finalized/activated."},"archived":{"type":"boolean","title":"Archived","description":"Whether the posting is archived."},"test_posting":{"type":"boolean","title":"Test Posting","description":"Whether this is a test posting."},"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."},"redirect_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Redirect Url","description":"URL candidates are redirected to after completing the interview."},"scheduling_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scheduling Url","description":"Calendar scheduling URL for shortlisted candidates."},"max_retakes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Retakes","description":"Maximum number of interview retakes allowed."},"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:\n- `source` (string): how the posting was created, e.g. `job_sync`.\n- `ats_name` (string): identifier of the ATS, e.g. `workable`, `bullhorn`.\n- `ats_job_id` (string): ID of the ATS job that backs this posting.\n- `ats_job_posting_id` (string, optional): ATS-side job-posting ID when distinct from `ats_job_id`.\n- `integration_id` (string, optional): heymilo ATS integration ID.\n- `job_ids` (string[], optional): ATS job IDs included in the mapping config.\n- `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.\n- `mapping_activated_at`, `mapping_activated_by` (read-only): audit fields stamped when the ATS mapping was attached.\n- `mapping_deactivated_at`, `mapping_deactivated_by` (read-only): audit fields stamped when the ATS mapping was last paused."},"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."},"created_at":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Created At","description":"Unix timestamp when the posting was created."},"updated_at":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Updated At","description":"Unix timestamp when the posting was last updated."}},"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.\n\nA posting represents a complete hiring pipeline — it defines the\njob, the AI agents involved, and how candidates progress through\neach screening step."},"WorkflowStep":{"properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id","description":"Unique identifier for this workflow step."},"type":{"type":"string","title":"Type","description":"Agent type: 'web_interview', 'conversational_sms', 'resume', 'form'."},"order":{"type":"integer","title":"Order","description":"Position in the workflow pipeline (1-based)."},"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."},"APIErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/APIError"}},"type":"object","required":["error"],"title":"APIErrorResponse"},"APIError":{"properties":{"type":{"type":"string","title":"Type","description":"Error category"},"code":{"type":"string","title":"Code","description":"Machine-readable error code"},"message":{"type":"string","title":"Message","description":"Human-readable summary"},"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"},"APIErrorDetail":{"properties":{"code":{"type":"string","title":"Code","description":"Machine-readable error code"},"message":{"type":"string","title":"Message","description":"Human-readable explanation"},"param":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Param","description":"Parameter that caused the error"}},"type":"object","required":["code","message"],"title":"APIErrorDetail"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/api/v2/postings/{posting_id}/clone":{"post":{"tags":["Interviewers"],"summary":"Clone an interviewer","description":"Create a copy of an existing interviewer with its workflow configuration.\n\nIf the source interviewer is ATS-derived, the clone is returned in the same intermediate stage as a fresh ATS create (`status: \"draft\"`, `ats_metadata.pending_activation: true`) and must be transitioned to live via `POST /postings/{posting_id}/activate`. Cloning a non-ATS posting is unchanged.","operationId":"clonePosting","parameters":[{"name":"posting_id","in":"path","required":true,"schema":{"type":"string","title":"Posting Id"}},{"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"}}],"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"}}}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.admin.heymilo.ai/api-next-gen/reference/interviewers.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.