Хантфлоу API v2: Добавить кандидата из формы на сайте на вакансию

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

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

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": "Отклик с карьерного сайта"}'

Базовые 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 /accounts — Доступные организации

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

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, которые игнорировать

Нюансы

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

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

• Открыть вакансию из своей системы
• Выгрузить кандидатов по вакансии и этапам
• Получать события через вебхук

---

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