Хантфлоу API v2 API

Отрасль: HR и рекрутинг. Актуально на 2026-10-24.

API рекрутинговой CRM Хантфлоу: организации и пользователи, вакансии и заявки на вакансии, кандидаты и их резюме, движение кандидатов по этапам подбора, загрузка и распознавание файлов резюме, метки, справочники, вебхуки, офферы, анкеты и журнал действий. Первая версия API устарела и не поддерживается — используется v2.

Сценарии

Добавить кандидата из формы на сайте на вакансию

Отклик с карьерного сайта сразу попадает в Хантфлоу: кандидат, резюме и этап подбора.

1. Создай токен: «Настройки» → «API» → «Добавить токен». access_token живёт 7 дней, refresh_token — 14; при ответе 401 с detail = token_expired обнови пару через POST /token/refresh.
2. Узнай ID организации: GET /accounts — account_id нужен во всех остальных методах.
3. Загрузи файл резюме: POST /accounts/{account_id}/upload (multipart) с заголовком x-file-parse: true — Хантфлоу распознает ФИО, контакты и опыт. Сохрани id файла.
4. Создай кандидата: POST /accounts/{account_id}/applicants с first_name, last_name, phone, email и externals — резюме с файлом.
5. Добавь кандидата на вакансию: POST /accounts/{account_id}/applicants/{applicant_id}/vacancy с vacancy и status — ID этапа подбора (список этапов — /accounts/{account_id}/vacancies/statuses).

H="Authorization: Bearer $HF_TOKEN"
API=https://api.huntflow.ru/v2/accounts/<account_id>

FILE_ID=$(curl -s -X POST "$API/upload" -H "$H" -H 'x-file-parse: true' -F file=@cv.pdf | jq -r .id)

APPLICANT=$(curl -s -X POST "$API/applicants" -H "$H" -H 'Content-Type: application/json' \
  -d "{\"first_name\": \"Иван\", \"last_name\": \"Петров\", \"phone\": \"+79990001122\", \"email\": \"ivan@example.ru\",
       \"externals\": [{\"auth_type\": \"NATIVE\", \"data\": {\"body\": \"Отклик с сайта\"}, \"files\": [$FILE_ID]}]}" | jq -r .id)

curl -X POST "$API/applicants/$APPLICANT/vacancy" -H "$H" -H 'Content-Type: application/json' \
  -d '{"vacancy": 101, "status": 1001, "comment": "Отклик с карьерного сайта"}'

Открыть вакансию из своей системы

Заявка на подбор согласована во внутренней системе — вакансия появляется в Хантфлоу.

1. Создай вакансию: POST /accounts/{account_id}/vacancies с position, company, money, body, requirements, conditions (HTML) и fill_quotas — квотой найма с deadline и applicants_to_hire.
2. Добавь коллег-рекрутеров через coworkers, скрыть вакансию от остальных — hidden = true.
3. Проверь список: GET /accounts/{account_id}/vacancies с state = OPEN и mine = true — только вакансии текущего пользователя.

curl -X POST https://api.huntflow.ru/v2/accounts/<account_id>/vacancies \
  -H "Authorization: Bearer $HF_TOKEN" -H 'Content-Type: application/json' \
  -d '{
        "position": "Python-разработчик",
        "company": "Отдел разработки",
        "money": "200 000 – 300 000 ₽",
        "requirements": "<ul><li>Python 3, FastAPI</li></ul>",
        "fill_quotas": [{"deadline": "2026-12-01", "applicants_to_hire": 2}]
      }'

Выгрузить кандидатов по вакансии и этапам

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

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.

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

Получать события через вебхук

Реагировать на смену этапа кандидата или новую вакансию сразу: уведомить менеджера, завести сотрудника в HR-системе.

1. Создай вебхук: POST /accounts/{account_id}/hooks с url, secret, active = true и webhook_events — нужными событиями (APPLICANT, VACANCY, RESPONSE, OFFER и др.).
2. Хантфлоу присылает события POST-запросом на url. Используй secret, чтобы отличать настоящие запросы, — способ проверки описан в документации вебхуков.
3. По ID из события получай актуальные данные: например, GET /accounts/{account_id}/applicants с vacancy_id.

curl -X POST https://api.huntflow.ru/v2/accounts/<account_id>/hooks \
  -H "Authorization: Bearer $HF_TOKEN" -H 'Content-Type: application/json' \
  -d '{"url": "https://example.ru/huntflow/webhook", "secret": "s3cr3t_Random_42", "active": true, "webhook_events": ["APPLICANT", "VACANCY"]}'

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

Методы

POST /token/refresh — Обновление токенов

В ответе: access_token, refresh_token, expires_in.

Параметр	Где	Тип	Обяз.	Описание
refresh_token	body	string	да	Refresh-токен

GET /me — Текущий пользователь

Информация о владельце токена.

GET /accounts — Доступные организации

Список организаций, к которым есть доступ; account_id из ответа нужен в остальных методах.

GET /accounts/{account_id}/vacancies — Список вакансий

Параметр	Где	Тип	Обяз.	Описание
account_id	path	integer	да	ID организации
count	query	integer	нет	Элементов на странице, по умолчанию 30
page	query	integer	нет	Номер страницы, по умолчанию 1
mine	query	boolean	нет	Только вакансии, с которыми работает текущий пользователь
state	query	string	нет	Состояние вакансии (можно несколько)

POST /accounts/{account_id}/vacancies — Создание вакансии

Также: GET/PUT/PATCH/DELETE /accounts/{account_id}/vacancies/{vacancy_id}; этапы подбора — GET /accounts/{account_id}/vacancies/statuses.

Параметр	Где	Тип	Обяз.	Описание
account_id	path	integer	да	ID организации
position	body	string	да	Название вакансии
company	body	string	нет	Отдел или компания
account_division	body	integer	нет	ID подразделения
account_region	body	integer	нет	ID региона
money	body	string	нет	Зарплата
priority	body	integer	нет	Приоритет
hidden	body	boolean	нет	Скрыть от коллег, по умолчанию false
state	body	string	нет	Состояние, по умолчанию OPEN
coworkers	body	array	нет	ID коллег, работающих с вакансией
body	body	string	нет	Обязанности (HTML)
requirements	body	string	нет	Требования (HTML)
conditions	body	string	нет	Условия (HTML)
files	body	array	нет	ID прикреплённых файлов
fill_quotas	body	array	да	Квота найма: deadline, applicants_to_hire (один элемент)

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

POST /accounts/{account_id}/applicants — Создание кандидата

Также: GET/PATCH/DELETE /accounts/{account_id}/applicants/{applicant_id}.

Параметр	Где	Тип	Обяз.	Описание
account_id	path	integer	да	ID организации
first_name	body	string	нет	Имя
last_name	body	string	нет	Фамилия
middle_name	body	string	нет	Отчество
phone	body	string	нет	Телефон
email	body	string	нет	Email
position	body	string	нет	Желаемая должность
company	body	string	нет	Компания
money	body	string	нет	Зарплатные ожидания
birthday	body	string	нет	Дата рождения
photo	body	integer	нет	ID фото
externals	body	array	нет	Резюме (одно): auth_type, account_source, data.body, files
social	body	array	нет	Соцсеть (одна): social_type (TELEGRAM), value

POST /accounts/{account_id}/applicants/{applicant_id}/vacancy — Добавление кандидата на вакансию

Смена этапа по уже добавленной вакансии — PUT по тому же пути.

Параметр	Где	Тип	Обяз.	Описание
account_id	path	integer	да	ID организации
applicant_id	path	integer	да	ID кандидата
vacancy	body	integer	да	ID вакансии
status	body	integer	да	ID этапа подбора
comment	body	string	нет	Комментарий
rejection_reason	body	integer	нет	ID причины отказа (для этапа отказа)
fill_quota	body	integer	нет	ID квоты (для этапа «вышел на работу»)
employment_date	body	string	нет	Дата выхода (для этапа «вышел на работу»)
files	body	array	нет	ID файлов, до 15
calendar_event	body	object	нет	Событие календаря (интервью)
email	body	object	нет	Письмо кандидату

POST /accounts/{account_id}/upload — Загрузка и распознавание файла

Файл отправляется в multipart/form-data.

Параметр	Где	Тип	Обяз.	Описание
account_id	path	integer	да	ID организации
file	body	file	да	Файл
x-file-parse	header	boolean	нет	Распознать поля резюме
x-ignore-lastname	header	string	нет	Фамилии, которые игнорировать при распознавании
x-ignore-email	header	string	нет	Email, которые игнорировать

POST /accounts/{account_id}/hooks — Создание вебхука

Параметр	Где	Тип	Обяз.	Описание
account_id	path	integer	да	ID организации
url	body	string	да	URL вебхука
secret	body	string	да	Секретный ключ
active	body	boolean	да	Активен ли вебхук
webhook_events	body	array	да	APPLICANT, VACANCY, RESPONSE, OFFER, VACANCY-REQUEST, RECRUITMENT-EVALUATION, SURVEY-QUESTIONARY
type	body	string	нет	USER (по умолчанию) или APPLICATION

Нюансы

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

Ошибки

Код	Описание
401	Нет авторизации или токен истёк (type: authorization_error, detail: token_expired)

Источники

• Huntflow API Reference v2
• Спецификация OpenAPI
• Официальный Python-клиент Хантфлоу
• Хантфлоу API v1 (устарел)

---

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