# Хантфлоу API v2: Выгрузить кандидатов по вакансии и этапам

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

Воронка подбора для отчёта: кто на каком этапе по каждой вакансии.

1. Для массовой выгрузки используй курсорный поиск: GET /accounts/{account_id}/applicants/search_by_cursor с vacancy, status (ID этапов) и only_current_status = true — только те, кто сейчас на этапе.
2. Для следующей страницы передай next_page_cursor из ответа — остальные параметры тогда не учитываются.
3. Для простых выборок подходит GET /accounts/{account_id}/applicants с vacancy_id и status, постранично через page и count.

```bash
curl -G https://api.huntflow.ru/v2/accounts/<account_id>/applicants/search_by_cursor \
  -H "Authorization: Bearer $HF_TOKEN" \
  -d vacancy=101 -d status=1002 -d only_current_status=true -d count=100
```

## Базовые URL

- Боевой: `https://api.huntflow.ru/v2`
- Тестовый (песочница): `https://sandbox.huntflow.dev`
- Официальный Python-клиент Хантфлоу по умолчанию указывает хост .: `https://api.huntflow.ai`

## Авторизация

Тип: Bearer-токен

Токен создаётся в настройках Хантфлоу: «Настройки» → «API» → «Добавить токен»; выдаётся пара `access_token` и `refresh_token`. Все запросы передают заголовок `Authorization: Bearer <access_token>`.

- `access_token` действует 7 дней, `refresh_token` — 14 дней; если refresh-токен не использовать 14 дней, пару нужно создать заново.
- Истёкший токен даёт `401` с `type: authorization_error` и `detail: token_expired` — тогда вызывайте `POST /token/refresh`.

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

### GET /accounts/{account_id}/applicants — Список кандидатов

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `account_id` | path | integer | да | ID организации |
| `count` | query | integer | нет | Элементов на странице, по умолчанию 30 |
| `page` | query | integer | нет | Номер страницы, по умолчанию 1 |
| `status` | query | integer | нет | ID этапа подбора |
| `vacancy_id` | query | integer | нет | ID вакансии |
| `agreement_state` | query | string | нет | Статус согласия на обработку ПДн; нельзя вместе со status |

### GET /accounts/{account_id}/applicants/search_by_cursor — Поиск кандидатов

Если передан `next_page_cursor`, остальные параметры не учитываются.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `account_id` | path | integer | да | ID организации |
| `next_page_cursor` | query | string | нет | Курсор следующей страницы |
| `q` | query | string | нет | Поисковый запрос |
| `status` | query | array | нет | ID этапов подбора |
| `vacancy` | query | array | нет | ID вакансий; null — кандидаты без вакансии |
| `only_current_status` | query | boolean | нет | Только кандидаты, находящиеся сейчас на этапе |
| `account_source` | query | array | нет | ID источников резюме |
| `count` | query | integer | нет | Элементов на странице, по умолчанию 30 |

## Нюансы

- Почти все методы работают в контексте организации: `account_id` берётся из `GET /accounts`.
- ID этапов подбора — из `GET /accounts/{account_id}/vacancies/statuses`, причины отказа — из `/rejection_reasons`, источники резюме — из `/applicants/sources`.
- Для массовой выборки кандидатов удобнее курсорный поиск `search_by_cursor`.
- Есть также методы заявок на вакансии, мультивакансий, меток, справочников, регионов, подразделений, офферов, анкет, журнала действий (`action_logs`) и производственного календаря.

## Другие сценарии

- [Добавить кандидата из формы на сайте на вакансию](https://mcp-everything.ru/integrations/huntflow/scenarios/dobavit-kandidata-iz-formy-na-sayte.md)
- [Открыть вакансию из своей системы](https://mcp-everything.ru/integrations/huntflow/scenarios/otkryt-vakansiyu-iz-svoey-sistemy.md)
- [Получать события через вебхук](https://mcp-everything.ru/integrations/huntflow/scenarios/poluchat-sobytiya-cherez-vebhuk.md)

---

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