HeadHunter API (hh.ru): POST /vacancies — Публикация вакансии

При успешной публикации списываются услуги работодателя; конкретный пакет задаётся employer_service_id, иначе выбирается автоматически. Все вакансии проходят ручную модерацию и появляются в поиске через несколько минут. Успех — 201.

Параметр	Где	Тип	Обяз.	Описание
ignore_duplicates	query	boolean	нет	Принудительно добавить дубликат
name	body	string	да	Название
description	body	string	да	Описание в HTML
area	body	object	да	Регион
professional_roles	body	array	да	Профессиональные роли
vacancy_properties	body	object	нет	Свойства публикации (заменяет устаревшие type и billing_type)
employer_service_id	body	string	нет	Пакет услуг из suitable_packages[].employer_service_id
salary_range	body	object	нет	Зарплата (поле salary устарело)
address	body	object	нет	Адрес
experience	body	object	нет	Опыт работы
employment_form	body	object	нет	Тип занятости
work_format	body	array	нет	Форматы работы
work_schedule_by_days	body	array	нет	Графики работы
working_hours	body	array	нет	Рабочие часы в день
key_skills	body	array	нет	Ключевые навыки
contacts	body	object	нет	Контакты; при использовании нужен атрибут phones
code	body	string	нет	Внутренний код вакансии
department	body	object	нет	Департамент работодателя
manager	body	object	нет	Менеджер вакансии
previous_id	body	string	нет	ID архивной вакансии для связи с новой
response_letter_required	body	boolean	нет	Обязательно сопроводительное письмо
test	body	object	нет	Тест для вакансии

Базовые URL

• Боевой: https://api.hh.ru
• Запросы ко всем сайтам группы идут на один адрес; нужный сайт задаётся параметром (по умолчанию ), локаль: ?host=

Авторизация

Тип: OAuth 2.0

OAuth 2.0. Токен передаётся в заголовке Authorization: Bearer {ACCESS_TOKEN}.

• Токен пользователя (authorization code): пользователь открывает https://hh.ru/oauth/authorize?response_type=code&client_id={client_id}&state={state}&redirect_uri={redirect_uri}, затем authorization_code из редиректа обменивается на access_token и refresh_token запросом POST https://api.hh.ru/token. Поддерживается PKCE (code_challenge, code_challenge_method=S256).
• Обновление: POST https://api.hh.ru/token с refresh_token; refresh-токен одноразовый и работает только после истечения access_token (срок — expires_in, в секундах).
• Токен приложения (client credentials): срок жизни не ограничен, при повторном запросе прежний отзывается; запрашивать не чаще раза в 5 минут. Актуальный токен виден владельцу на https://dev.hh.ru/admin.

Параметры /oauth/authorize: skip_choose_account=true — не показывать выбор аккаунта, force_login=true — всегда показывать форму входа, role (applicant или employer) с force_role=true — требовать нужную роль.

В каждом запросе обязателен заголовок User-Agent или HH-User-Agent (при обоих учитывается HH-User-Agent); без него — 400 Bad Request.

User-Agent: MyApp/1.0 (my-app-feedback@example.com)

Нюансы

• Пагинация: page=N&per_page=M, нумерация с нуля; ответ — found, per_page, pages, page, items.
• Неизвестные и недокументированные параметры игнорируются; недокументированные поля в ответах не рекомендуется использовать.
• Длинные ответы сжимаются gzip.
• Поддерживается CORS; для отладки есть /cors (HEAD, GET, POST, PUT, DELETE), для JSONP — ?callback=callback_name.
• Вебхуки: на одно приложение — один URL. Ваш сервер отвечает 2xx или 409 для дубликата (определяется по id). Без ответа за 5 секунд колбэк отправляется повторно; доставка не гарантирована. При долгих сбоях подписка блокируется, при отзыве доступа удаляется.
• Методы /negotiations/{nid}/messages устарели — переписка ведётся через /common/chats.
• Просмотр резюме с контактами списывает контакт один раз на компанию; если контакты скрыты соискателем, просмотр всё равно спишется — проверяйте hidden_fields.

Сценарии с этим методом

• Опубликовать вакансию от имени работодателя

---

Если этого недостаточно — официальная документация: https://api.hh.ru/openapi/redoc Вся интеграция одним документом: https://mcp-everything.ru/integrations/hh-api.md