HeadHunter API (hh.ru): Разобрать отклики на вакансию

Сценарий из mcp-everything. Актуально на 2026-10-24.

Забирать откликнувшихся кандидатов в свою систему и приглашать или отказывать без захода на hh.ru.

Получи отклики: GET /negotiations с vacancy_id (обязателен для работодателя) и, например, has_updates = true — только с непросмотренным.
Открой отклик: GET /negotiations/{id} — адрес берётся из items[].url. Резюме кандидата смотри через ссылку из отклика.
Чтобы пригласить или отказать, возьми из actions[] нужное действие и вызови PUT /negotiations/{collection_name}/{nid} с аргументами из actions[].arguments (form-urlencoded). Успех — 204.
Не составляй адреса действий вручную: доступные действия зависят от состояния отклика и приходят в ответе.

curl -G https://api.hh.ru/negotiations \
  -H "Authorization: Bearer $HH_TOKEN" -H 'HH-User-Agent: MyApp/1.0 (dev@example.ru)' \
  -d vacancy_id=123456789 -d has_updates=true -d per_page=50

Базовые 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)

Методы сценария

GET /negotiations — Список откликов и приглашений

По умолчанию сортировка по дате обновления, от новых к старым. Активные отклики — ?status=active.

Параметр	Где	Тип	Обяз.	Описание
`vacancy_id`	query	string	да	ID вакансии (обязателен для работодателя)
`status`	query	string	нет	Статус из applicant_negotiation_status
`order_by`	query	string	нет	Сортировка из negotiations_order
`order`	query	string	нет	asc или desc
`has_updates`	query	boolean	нет	Только с непросмотренными сообщениями
`with_job_search_status`	query	boolean	нет	Вернуть статус поиска работы кандидата
`with_generated_collections`	query	boolean	нет	Вернуть сгенерированные коллекции
`page`	query	number	нет	Номер страницы
`per_page`	query	number	нет	По умолчанию 20

GET /negotiations/{id} — Просмотр отклика или приглашения

URL берётся из items[].url списка откликов.

Параметр	Где	Тип	Обяз.	Описание
`id`	path	string	да	Идентификатор отклика

PUT /negotiations/{collection_name}/{nid} — Действие с откликом

Меняет работодательское (employer_state) или соискательское (state) состояние: отложить, пригласить на интервью, отказать. Доступные действия и их URL — в actions[] списка откликов; аргументы из actions[].arguments передаются как application/x-www-form-urlencoded. Успех — 204.

Параметр	Где	Тип	Обяз.	Описание
`collection_name`	path	string	да	Коллекция из collections[].id
`nid`	path	string	да	Идентификатор отклика

Нюансы

Пагинация: 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