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>",
  "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"
  }
}
'
import requests

url = "https://api.heymilo.ai/api/v2/postings/{posting_id}"

payload = {
    "title": "<string>",
    "description": "<string>",
    "name": "<string>",
    "language": "<string>",
    "interviewer_name": "<string>",
    "instructions": "<string>",
    "company_overview": "<string>",
    "job_overview": "<string>",
    "interview_process_overview": "<string>",
    "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"
    }
}
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'PATCH',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    title: '<string>',
    description: '<string>',
    name: '<string>',
    language: '<string>',
    interviewer_name: '<string>',
    instructions: '<string>',
    company_overview: '<string>',
    job_overview: '<string>',
    interview_process_overview: '<string>',
    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'}
  })
};

fetch('https://api.heymilo.ai/api/v2/postings/{posting_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.heymilo.ai/api/v2/postings/{posting_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'title' => '<string>',
    'description' => '<string>',
    'name' => '<string>',
    'language' => '<string>',
    'interviewer_name' => '<string>',
    'instructions' => '<string>',
    'company_overview' => '<string>',
    'job_overview' => '<string>',
    'interview_process_overview' => '<string>',
    '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'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.heymilo.ai/api/v2/postings/{posting_id}"

	payload := strings.NewReader("{\n  \"title\": \"<string>\",\n  \"description\": \"<string>\",\n  \"name\": \"<string>\",\n  \"language\": \"<string>\",\n  \"interviewer_name\": \"<string>\",\n  \"instructions\": \"<string>\",\n  \"company_overview\": \"<string>\",\n  \"job_overview\": \"<string>\",\n  \"interview_process_overview\": \"<string>\",\n  \"phone_number_id\": \"<string>\",\n  \"sender_email_id\": \"<string>\",\n  \"email_template_group_id\": \"<string>\",\n  \"design_template_group_id\": \"<string>\",\n  \"redirect_url\": \"<string>\",\n  \"scheduling_url\": \"<string>\",\n  \"deadline\": \"<string>\",\n  \"allow_sms_comms\": true,\n  \"max_retakes\": 2,\n  \"retake_cooldown_days\": 1,\n  \"email_report_to_candidate\": true,\n  \"metadata\": {\n    \"external_id\": \"ats_12345\",\n    \"source\": \"workday\"\n  }\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("X-API-KEY", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.patch("https://api.heymilo.ai/api/v2/postings/{posting_id}")
  .header("X-API-KEY", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"title\": \"<string>\",\n  \"description\": \"<string>\",\n  \"name\": \"<string>\",\n  \"language\": \"<string>\",\n  \"interviewer_name\": \"<string>\",\n  \"instructions\": \"<string>\",\n  \"company_overview\": \"<string>\",\n  \"job_overview\": \"<string>\",\n  \"interview_process_overview\": \"<string>\",\n  \"phone_number_id\": \"<string>\",\n  \"sender_email_id\": \"<string>\",\n  \"email_template_group_id\": \"<string>\",\n  \"design_template_group_id\": \"<string>\",\n  \"redirect_url\": \"<string>\",\n  \"scheduling_url\": \"<string>\",\n  \"deadline\": \"<string>\",\n  \"allow_sms_comms\": true,\n  \"max_retakes\": 2,\n  \"retake_cooldown_days\": 1,\n  \"email_report_to_candidate\": true,\n  \"metadata\": {\n    \"external_id\": \"ats_12345\",\n    \"source\": \"workday\"\n  }\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.heymilo.ai/api/v2/postings/{posting_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"title\": \"<string>\",\n  \"description\": \"<string>\",\n  \"name\": \"<string>\",\n  \"language\": \"<string>\",\n  \"interviewer_name\": \"<string>\",\n  \"instructions\": \"<string>\",\n  \"company_overview\": \"<string>\",\n  \"job_overview\": \"<string>\",\n  \"interview_process_overview\": \"<string>\",\n  \"phone_number_id\": \"<string>\",\n  \"sender_email_id\": \"<string>\",\n  \"email_template_group_id\": \"<string>\",\n  \"design_template_group_id\": \"<string>\",\n  \"redirect_url\": \"<string>\",\n  \"scheduling_url\": \"<string>\",\n  \"deadline\": \"<string>\",\n  \"allow_sms_comms\": true,\n  \"max_retakes\": 2,\n  \"retake_cooldown_days\": 1,\n  \"email_report_to_candidate\": true,\n  \"metadata\": {\n    \"external_id\": \"ats_12345\",\n    \"source\": \"workday\"\n  }\n}"

response = http.request(request)
puts response.read_body
{
  "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",
      "pending_activation": true,
      "source": "job_sync"
    },
    "metadata": {
      "external_id": "ats_12345",
      "source": "workday"
    },
    "created_at": 1739612400,
    "updated_at": 1739617200
  },
  "meta": {}
}
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "errors": [
      {
        "code": "<string>",
        "message": "<string>",
        "param": "title"
      }
    ]
  }
}
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "errors": [
      {
        "code": "<string>",
        "message": "<string>",
        "param": "title"
      }
    ]
  }
}
{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "errors": [
      {
        "code": "<string>",
        "message": "<string>",
        "param": "title"
      }
    ]
  }
}

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 | null
​
Authorization
string | null
​
X-Workspace-Id
string | null

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 | null

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 | null

Optional metadata. Shape varies by endpoint.