v1

latestOpenAPI 3.1.02026-08-0456127224.3 KB

Interviewers

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.

post/api/v2/postings

Headers

X-API-KEYstring nullable

Authorizationstring nullable

X-Workspace-Idstring nullable

Request body

titlestring required

Job posting title

descriptionstring

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

interview_template_idstring nullable

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.

namestring nullable

Internal posting slug

languagestring

Interview language (ISO 639-1)

interviewer_namestring

AI interviewer display name

instructionsstring

Instructions for the AI interviewer

company_overviewstring

Brief overview of the company

job_overviewstring

Brief overview of the role

interview_process_overviewstring nullable

Process overview shared with agents.

company_overview_delivery_mode'exact_delivery' | 'summarized_delivery' | 'reference_only' | 'silent_reference' nullable

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'exact_delivery' | 'summarized_delivery' | 'reference_only' | 'silent_reference' nullable

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

interview_process_overview_delivery_mode'exact_delivery' | 'summarized_delivery' | 'reference_only' | 'silent_reference' nullable

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

phone_number_idstring nullable

Phone number ID for SMS and voice agents.

sender_email_idstring nullable

Sender email ID for candidate communications.

email_template_group_idstring nullable

Email template group ID for candidate emails.

design_template_group_idstring nullable

Design template group ID for interview UI branding.

redirect_urlstring nullable

URL to redirect candidates after completing the interview.

scheduling_urlstring nullable

Calendar scheduling URL for shortlisted candidates.

deadlinestring nullable

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_commsboolean nullable

Allow sending SMS invitations to candidates.

max_retakesinteger nullable

Max retake attempts (0-5).

retake_cooldown_daysnumber nullable

Days a candidate must wait between retake attempts.

email_report_to_candidateboolean nullable

Email a performance report link to candidates after completion.

metadataobject nullable

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

Example request

{
  "title": "Senior Software Engineer",
  "workflow": [
    {
      "config": {
        "voice_id": "voice-1",
        "interview_type": "general",
        "prompt_version": "v2"
      }
    }
  ],
  "interview_template_id": "IT_abc123",
  "name": "senior-swe-backend",
  "language": "en",
  "deadline": "2025-03-15T00:00:00Z",
  "metadata": {
    "external_id": "ats_12345",
    "source": "workday"
  }
}

Response

Successful Response

metaobject nullable

Optional metadata. Shape varies by endpoint.

Example response

{
  "data": {
    "id": "13D77095",
    "status": "active",
    "urls": {
      "candidate_url": "https://candidates.heymilo.io/acme/senior-engineer",
      "ingestion_url_key": "ibURejyPMSlw6de0OZUdoxyoXTgWO78ey2NUo96EOG1gY",
      "review_url": "https://admin.heymilo.ai/w/ABC123/lab2/POST_ID/1-details"
    },
    "created_at": 1739612400,
    "posting": {
      "id": "13D77095",
      "company_id": "comp_abc123",
      "title": "Senior Software Engineer",
      "name": "senior-software-engineer",
      "description": "We are looking for a senior software engineer...",
      "language": "en",
      "interviewer_name": "Sarah",
      "status": "active",
      "finalized": true,
      "workflow": [
        {
          "id": "agent_vi_001",
          "type": "web_interview",
          "order": 1
        }
      ],
      "urls": {
        "candidate_url": "https://candidates.heymilo.io/acme/senior-engineer",
        "ingestion_url_key": "ibURejyPMSlw6de0OZUdoxyoXTgWO78ey2NUo96EOG1gY",
        "review_url": "https://admin.heymilo.ai/w/ABC123/lab2/POST_ID/1-details"
      },
      "deadline": 1775174400,
      "redirect_url": "https://acme.com/thank-you",
      "scheduling_url": "https://cal.com/acme/interview",
      "max_retakes": 1,
      "ats_metadata": {
        "ats_job_id": "WK-12345",
        "ats_name": "workable",
        "pending_activation": true,
        "source": "job_sync"
      },
      "metadata": {
        "external_id": "ats_12345",
        "source": "workday"
      },
      "created_at": 1739612400,
      "updated_at": 1739617200
    }
  }
}