# HeadHunter API (hh.ru): GET /resumes — Поиск резюме

Результаты группируются по соискателю (одно резюме на соискателя). Глубина выдачи — не больше 2000. Для тонкой настройки `text` передаётся вся триада `text.logic`, `text.field`, `text.period`.

Пример:

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `text` | query | string | нет | Поисковая фраза; можно несколько |
| `text.logic` | query | string | нет | Логика поиска из resume_search_logic |
| `text.field` | query | string | нет | Где искать, из resume_search_fields (через запятую) |
| `text.period` | query | string | нет | Период опыта работы |
| `area` | query | string | нет | Регион; можно несколько |
| `relocation` | query | string | нет | Готовность к переезду (вместе с area) |
| `age_from` | query | string | нет | Возраст от |
| `age_to` | query | string | нет | Возраст до |
| `salary_from` | query | number | нет | Желаемая зарплата от |
| `salary_to` | query | number | нет | Желаемая зарплата до |
| `currency` | query | string | нет | Код валюты |
| `experience` | query | string | нет | Опыт работы; можно несколько |
| `skill` | query | string | нет | ID ключевых навыков |
| `professional_role` | query | string | нет | Профессиональная роль; можно несколько |
| `language` | query | string | нет | Язык в формате language.level, например ita.c2 |
| `label` | query | string | нет | Доп. фильтр из resume_search_label; можно несколько |
| `period` | query | number | нет | Резюме, опубликованные за N дней |
| `date_from` | query | string | нет | Дата начала поиска; нельзя с period |
| `date_to` | query | string | нет | Дата окончания (только с date_from) |
| `vacancy_id` | query | string | нет | Поиск резюме, похожих на вакансию |
| `search_in_responses` | query | boolean | нет | Искать только среди откликнувшихся на вакансии компании |
| `folder` | query | string | нет | Папки с отобранными резюме, например folder=111&folder=222 |
| `order_by` | query | string | нет | Сортировка из resume_search_order |
| `page` | query | number | нет | Номер страницы, с 0 |
| `per_page` | query | number | нет | По умолчанию 20, максимум 100 |

Пример запроса:

```
GET /resumes?text=программист&text=java
```

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