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

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

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

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 — только вакансии текущего пользователя.

```bash
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}]
      }'
```

## Базовые 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}/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 (один элемент) |

## Нюансы

- Почти все методы работают в контексте организации: `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/vygruzit-kandidatov-po-vakansii-i-etapam.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