Skip to main content
PATCH
/
api
/
v2
/
postings
/
{posting_id}
Update an interviewer
curl --request PATCH \
  --url https://api.heymilo.ai/api/v2/postings/{posting_id} \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "title": "<string>",
  "description": "<string>",
  "name": "<string>",
  "language": "<string>",
  "interviewer_name": "<string>",
  "instructions": "<string>",
  "company_overview": "<string>",
  "job_overview": "<string>",
  "interview_process_overview": "<string>",
  "company_overview_delivery_mode": "exact_delivery",
  "job_overview_delivery_mode": "exact_delivery",
  "interview_process_overview_delivery_mode": "exact_delivery",
  "phone_number_id": "<string>",
  "sender_email_id": "<string>",
  "email_template_group_id": "<string>",
  "design_template_group_id": "<string>",
  "redirect_url": "<string>",
  "scheduling_url": "<string>",
  "deadline": "<string>",
  "allow_sms_comms": true,
  "max_retakes": 2,
  "retake_cooldown_days": 1,
  "email_report_to_candidate": true,
  "metadata": {
    "external_id": "ats_12345",
    "source": "workday"
  }
}
'
{
  "data": {
    "id": "<string>",
    "company_id": "<string>",
    "title": "<string>",
    "description": "<string>",
    "status": "<string>",
    "finalized": true,
    "archived": true,
    "test_posting": true,
    "object": "posting",
    "name": "senior-software-engineer",
    "language": "en",
    "interviewer_name": "Sarah",
    "workflow": [
      {
        "type": "<string>",
        "order": 123,
        "id": "agent_vi_001",
        "config": {}
      }
    ],
    "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,
    "allow_sms_comms": false,
    "instructions": "<string>",
    "company_overview": "<string>",
    "job_overview": "<string>",
    "interview_process_overview": "<string>",
    "company_overview_delivery_mode": "<string>",
    "job_overview_delivery_mode": "<string>",
    "interview_process_overview_delivery_mode": "<string>",
    "phone_number_id": "<string>",
    "sender_email_id": "<string>",
    "email_template_group_id": "<string>",
    "design_template_group_id": "<string>",
    "retake_cooldown_days": 123,
    "email_report_to_candidate": false,
    "ats_metadata": {
      "ats_job_id": "WK-12345",
      "ats_name": "workable",
      "source": "job_sync"
    },
    "metadata": {
      "external_id": "ats_12345",
      "source": "workday"
    },
    "created_at": 1739612400,
    "updated_at": 1739617200
  },
  "meta": {}
}

Documentation Index

Fetch the complete documentation index at: https://docs.heymilo.ai/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
X-API-KEY
string
header
required

API key for authentication. Pass your key in the X-API-KEY header.

Headers

​
X-API-KEY
string
required

Path Parameters

​
posting_id
string
required

Body

application/json

Request body for updating a posting. All fields are optional.

​
title
string | null

Updated job title.

Required string length: 3 - 200
​
description
string | null

Updated job description.

Required string length: 10 - 50000
​
name
string | null

Updated URL slug.

Maximum string length: 100
​
language
string | null

Updated default language (BCP-47).

​
interviewer_name
string | null

Updated AI interviewer display name.

Maximum string length: 100
​
instructions
string | null

Updated global instructions for the AI interviewer.

Maximum string length: 10000
​
company_overview
string | null

Updated company overview.

Maximum string length: 10000
​
job_overview
string | null

Updated job overview.

Maximum string length: 10000
​
interview_process_overview
string | null

Updated process overview shared with agents.

Maximum string length: 10000
​
company_overview_delivery_mode
enum<string> | null

Updated company overview delivery mode.

Available options:
exact_delivery,
summarized_delivery,
reference_only,
silent_reference
​
job_overview_delivery_mode
enum<string> | null

Updated job overview delivery mode.

Available options:
exact_delivery,
summarized_delivery,
reference_only,
silent_reference
​
interview_process_overview_delivery_mode
enum<string> | null

Updated interview process overview delivery mode.

Available options:
exact_delivery,
summarized_delivery,
reference_only,
silent_reference
​
phone_number_id
string | null

Updated phone number ID.

​
sender_email_id
string | null

Updated sender email ID.

​
email_template_group_id
string | null

Updated email template group ID.

​
design_template_group_id
string | null

Updated design template group ID.

​
redirect_url
string | null

Updated post-completion redirect URL.

​
scheduling_url
string | null

Updated scheduling URL for shortlisted candidates.

​
deadline
string | null

Updated ISO 8601 deadline.

​
allow_sms_comms
boolean | null

Updated SMS communications flag.

​
max_retakes
integer | null

Updated max retake attempts (0-5).

Required range: 0 <= x <= 5
​
retake_cooldown_days
number | null

Updated retake cooldown in days.

Required range: x >= 0
​
email_report_to_candidate
boolean | null

Updated email report flag.

​
metadata
Metadata · object

Updated key-value metadata. Replaces existing metadata entirely. Up to 50 keys, each key max 40 chars, each value max 500 chars.

Example:
{
  "external_id": "ats_12345",
  "source": "workday"
}

Response

Successful Response

​
data
PostingResponse · object
required

A job posting with its full agentic workflow configuration.

A posting represents a complete hiring pipeline — it defines the job, the AI agents involved, and how candidates progress through each screening step.

​
meta
Meta · object

Optional metadata. Shape varies by endpoint.