# Huntflow API v1 Documentation

Huntflow API is a RESTful service that enables integration with the Huntflow Applicant Tracking System (ATS). The API allows developers to build integrations for career sites, intranets, and other recruitment applications by providing programmatic access to manage vacancies, candidates, and hiring workflows. All API communication occurs over HTTPS using JSON data format, with OAuth 2.0 or personal tokens for authentication.

The API base URL is `https://api.huntflow.ru/` and requires a `User-Agent` header with every request. Rate limiting is set at 10 requests per second per token. Note: This documentation covers API v1 which is deprecated - users should migrate to v2 at `https://api.huntflow.ai/v2/docs`.

---

## Authentication with Personal Token

Personal tokens provide a simplified authentication method for server scripts and integrations without the OAuth 2.0 flow. Tokens are issued from Huntflow system settings with a 7-day access token lifetime and 14-day refresh token lifetime.

```bash
# Using personal token for API requests
curl -X GET "https://api.huntflow.ru/me" \
  -H "User-Agent: MyApp/1.0 (contact@example.com)" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access_token>"

# Response:
{
    "id": 3123123,
    "name": "John Doe",
    "position": "HRD",
    "email": "hello@huntflow.ru",
    "phone": "84956478221",
    "locale": "ru_RU"
}
```

---

## OAuth 2.0 Authorization Flow

OAuth 2.0 enables third-party applications to access user data without storing credentials. The flow involves redirecting users to authorize access, then exchanging the authorization code for access and refresh tokens.

```bash
# Step 1: Redirect user to authorization page
# User navigates to:
https://huntflow.ru/oauth/authorize?response_type=code&client_id={client_id}&state={state}&redirect_uri={redirect_uri}

# Step 2: After user approval, exchange authorization_code for tokens
curl -X POST "https://huntflow.ru/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&client_id={client_id}&client_secret={client_secret}&code={authorization_code}&redirect_uri={redirect_uri}"

# Response:
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6...",
  "token_type": "bearer",
  "expires_in": 259200,
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4..."
}

# Step 3: Refresh tokens when access_token expires
curl -X POST "https://huntflow.ru/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token&refresh_token={refresh_token}"
```

---

## Token Refresh (v2 Endpoint)

Refresh expired access tokens issued from the Huntflow interface. This endpoint can only be called after the access token has expired.

```bash
curl -X POST "https://api.huntflow.ru/v2/token/refresh" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyApp/1.0 (contact@example.com)" \
  -d '{
    "refresh_token": "<expired_refresh_token>"
  }'

# Response:
{
    "access_token": "<new_access_token>",
    "token_type": "bearer",
    "expires_in": 604800,
    "refresh_token_expires_in": 1209600,
    "refresh_token": "<new_refresh_token>"
}
```

---

## Get Current User Information

Returns information about the authenticated user. Useful for verifying token validity and retrieving user context.

```bash
curl -X GET "https://api.huntflow.ru/me" \
  -H "User-Agent: MyApp/1.0 (contact@example.com)" \
  -H "Authorization: Bearer <access_token>"

# Response:
{
    "id": 3123123,
    "name": "John Doe",
    "position": "HRD",
    "email": "hello@huntflow.ru",
    "phone": "84956478221",
    "locale": "ru_RU"
}
```

---

## List Available Organizations

Returns all organizations accessible to the authenticated user. The organization ID is required for most subsequent API calls.

```bash
curl -X GET "https://api.huntflow.ru/accounts" \
  -H "User-Agent: MyApp/1.0 (contact@example.com)" \
  -H "Authorization: Bearer <access_token>"

# Response:
{
    "items": [
        {
            "id": 123,
            "name": "Tesla",
            "nick": "tesla",
            "member_type": "owner"
        },
        {
            "id": 125,
            "name": "HR Systems",
            "nick": "hr-systems",
            "member_type": "manager"
        }
    ]
}
```

---

## Create a Vacancy

Creates a new vacancy in the organization's job database with position details, requirements, and hiring quotas.

```bash
curl -X POST "https://api.huntflow.ru/account/123/vacancies" \
  -H "User-Agent: MyApp/1.0 (contact@example.com)" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "position": "Manufacturing Engineer",
    "company": "Tesla",
    "money": "$100k",
    "priority": 1,
    "account_division": 6,
    "coworkers": [1],
    "body": "<p>Design and improve manufacturing processes</p>",
    "requirements": "<p>5+ years experience in manufacturing</p>",
    "conditions": "<p>Competitive salary, stock options</p>",
    "hidden": false,
    "state": "OPEN",
    "fill_quotas": [
        {
            "deadline": "2024-09-03",
            "applicants_to_hire": 2,
            "vacancy_request": 11
        }
    ]
  }'

# Response:
{
    "id": 4531,
    "position": "Manufacturing Engineer",
    "company": "Tesla",
    "money": "$100k",
    "deadline": "2024-09-03",
    "applicants_to_hire": 2,
    "created": "2024-04-10T21:34:01+03:00",
    "priority": 1,
    "hidden": false,
    "state": "OPEN"
}
```

---

## List Vacancies

Retrieves all vacancies for an organization with optional filtering by status and assignee.

```bash
# Get all open vacancies assigned to current user
curl -X GET "https://api.huntflow.ru/account/123/vacancies?mine=true&opened=true&page=1&count=30" \
  -H "User-Agent: MyApp/1.0 (contact@example.com)" \
  -H "Authorization: Bearer <access_token>"

# Response:
{
    "items": [
        {
            "id": 4531,
            "position": "Sales Manager",
            "company": "Sales Department",
            "money": "$65K",
            "deadline": "2024-04-27",
            "applicants_to_hire": 1,
            "created": "2024-03-22T18:16:27+03:00",
            "priority": 0,
            "hidden": false,
            "state": "OPEN"
        },
        {
            "id": 4530,
            "position": "Python Developer",
            "company": "DEV Department",
            "money": "$112K",
            "deadline": null,
            "applicants_to_hire": 1,
            "created": "2024-03-22T18:16:27+03:00",
            "priority": 0,
            "hidden": false,
            "state": "CLOSED"
        }
    ],
    "total": 2,
    "page": 1,
    "count": 30
}
```

---

## Get Vacancy Details

Retrieves full details of a specific vacancy including description, requirements, conditions, and attached files.

```bash
curl -X GET "https://api.huntflow.ru/account/123/vacancies/4531" \
  -H "User-Agent: MyApp/1.0 (contact@example.com)" \
  -H "Authorization: Bearer <access_token>"

# Response:
{
    "id": 4531,
    "position": "Sales Manager",
    "company": "Sales Department",
    "money": "$65K",
    "deadline": "2024-04-27",
    "applicants_to_hire": 1,
    "created": "2024-03-22T18:16:27+03:00",
    "priority": 0,
    "hidden": false,
    "state": "OPEN",
    "body": "<p>Responsible for enterprise sales</p>",
    "requirements": "<p>3+ years B2B sales experience</p>",
    "conditions": "<p>Base salary plus commission</p>",
    "files": [
        {
            "id": 15808,
            "name": "job_description.pdf",
            "content_type": "application/pdf",
            "url": "https://store.huntflow.ru/uploads/f/f/h/ffhov94xuqytbl16u8b9l3oeewdjpyoc.pdf"
        }
    ]
}
```

---

## Update a Vacancy

Updates an existing vacancy's details. Supports partial updates with the same fields as creation.

```bash
curl -X PUT "https://api.huntflow.ru/account/123/vacancies/4531" \
  -H "User-Agent: MyApp/1.0 (contact@example.com)" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "position": "Senior Sales Manager",
    "money": "$80K",
    "state": "OPEN",
    "priority": 1,
    "fill_quotas": [
        {
            "id": 64,
            "deadline": "2024-10-15",
            "applicants_to_hire": 3
        }
    ]
  }'

# Response:
{
    "id": 4531,
    "position": "Senior Sales Manager",
    "money": "$80K",
    "created": "2024-03-22T18:16:27+03:00",
    "priority": 1,
    "hidden": false,
    "state": "OPEN"
}
```

---

## Delete a Vacancy

Permanently removes a vacancy from the organization's database.

```bash
curl -X DELETE "https://api.huntflow.ru/account/123/vacancies/4531" \
  -H "User-Agent: MyApp/1.0 (contact@example.com)" \
  -H "Authorization: Bearer <access_token>"

# Response:
{
    "status": true
}
```

---

## Add Candidate to Database

Creates a new candidate record in the organization's applicant database with personal information and resume data.

```bash
curl -X POST "https://api.huntflow.ru/account/123/applicants" \
  -H "User-Agent: MyApp/1.0 (contact@example.com)" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "last_name": "Doe",
    "first_name": "John",
    "middle_name": "Michael",
    "phone": "89260731778",
    "email": "doe@gmail.com",
    "position": "Front-end Developer",
    "company": "Tech Corp",
    "money": "$100000",
    "birthday_day": 20,
    "birthday_month": 7,
    "birthday_year": 1984,
    "photo": 12341,
    "externals": [
        {
            "data": {
                "body": "Experienced front-end developer with 5 years of React expertise..."
            },
            "auth_type": "NATIVE",
            "files": [
                {"id": 12430}
            ],
            "account_source": 208
        }
    ]
  }'

# Response:
{
    "id": 123321,
    "created": "2024-04-10T21:34:01+03:00",
    "doubles": [
        {"double": 123320}
    ],
    "agreement": {
        "state": "not_sent",
        "decision_date": null
    }
}
```

---

## Add Candidate to Vacancy

Associates an existing candidate with a vacancy and assigns them to a hiring stage.

```bash
curl -X POST "https://api.huntflow.ru/account/123/applicants/123321/vacancy" \
  -H "User-Agent: MyApp/1.0 (contact@example.com)" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "vacancy": 4531,
    "status": 1230,
    "comment": "Strong candidate, schedule interview",
    "files": [
        {"id": 1382810}
    ],
    "rejection_reason": null
  }'

# Response:
{
    "id": 279284,
    "changed": "2024-04-10T21:34:01+03:00"
}
```

---

## List Candidates

Retrieves candidates with optional filtering by hiring stage, vacancy, and data processing agreement status.

```bash
curl -X GET "https://api.huntflow.ru/account/123/applicants?status=206&vacancy=4531&page=1&count=30" \
  -H "User-Agent: MyApp/1.0 (contact@example.com)" \
  -H "Authorization: Bearer <access_token>"

# Response:
{
  "count": 2,
  "items": [
    {
      "id": 290,
      "last_name": "Doe",
      "first_name": "John",
      "middle_name": null,
      "phone": "+79511234567",
      "email": "hello@mail.ru",
      "position": "Artist",
      "company": "Save Factory",
      "money": "",
      "birthday": "1979-06-20",
      "photo": 385,
      "photo_url": "https://store.huntflow.ru/uploads/5/7/0/5700c66c07a23f2e80a0acc0bc3ef6c8.jpeg",
      "created": "2024-12-19T21:48:12+03:00",
      "links": [
        {
          "id": 172,
          "vacancy": 1,
          "status": 2,
          "updated": "2024-12-19T21:48:12+03:00",
          "changed": "2024-12-19T21:48:12+03:00"
        }
      ],
      "external": [
        {
          "id": 290,
          "auth_type": "HH",
          "account_source": 2,
          "updated": "2024-12-19T21:48:12+03:00",
          "applicant": 290
        }
      ],
      "doubles": []
    }
  ],
  "total": 120,
  "page": 1,
  "total_items": 240
}
```

---

## Upload File with Resume Parsing

Uploads a file (resume) and optionally parses it to extract candidate information using OCR/NLP recognition.

```bash
curl -X POST "https://api.huntflow.ru/account/123/upload" \
  -H "User-Agent: MyApp/1.0 (contact@example.com)" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: multipart/form-data" \
  -H "X-File-Parse: true" \
  -F "file=@resume.pdf"

# Response:
{
    "id": 1329115,
    "name": "John Doe.pdf",
    "content_type": "application/pdf",
    "url": "https://store.huntflow.ru/uploads/t/f/9/tf96318hrjj5w9o5m9xuvwwwzbgbgave.pdf",
    "text": "Full resume text extracted from PDF...",
    "photo": {
        "id": 1352599,
        "name": "image1.png",
        "url": "https://store.huntflow.ru/uploads/6/p/p/6ppzo93d8ic8slkzy7flrabqemnwtzpq.png",
        "content_type": "image/png"
    },
    "fields": {
        "position": "Front-end Team Lead",
        "email": "doe@gmail.com",
        "salary": 200000,
        "name": {
            "first": "John",
            "middle": "Michael",
            "last": "Doe"
        },
        "phones": ["+7 (926) 073-17-78"],
        "birthdate": {
            "day": 20,
            "month": 7,
            "year": 1984,
            "precision": "day"
        },
        "experience": [
            {"position": "Mobile Team Lead", "company": "HeadHunter"},
            {"position": "Senior Frontend Developer", "company": "HeadHunter"}
        ]
    }
}
```

---

## Get Hiring Stages (Statuses)

Retrieves the list of hiring pipeline stages configured for the organization.

```bash
curl -X GET "https://api.huntflow.ru/account/123/vacancy/statuses" \
  -H "User-Agent: MyApp/1.0 (contact@example.com)" \
  -H "Authorization: Bearer <access_token>"

# Response:
{
    "items": [
        {
            "id": 206,
            "type": "user",
            "order": 1,
            "name": "New Lead",
            "removed": null
        },
        {
            "id": 207,
            "type": "user",
            "order": 2,
            "name": "Hired",
            "removed": null
        },
        {
            "id": 215,
            "type": "trash",
            "order": 9999,
            "name": "Declined",
            "removed": null
        }
    ]
}
```

---

## Get Resume Sources

Retrieves available resume sources (job boards, agencies) configured for the organization.

```bash
curl -X GET "https://api.huntflow.ru/account/123/applicant/sources" \
  -H "User-Agent: MyApp/1.0 (contact@example.com)" \
  -H "Authorization: Bearer <access_token>"

# Response:
{
    "items": [
        {
            "id": 209,
            "name": "Agency",
            "type": "user",
            "foreign": null
        },
        {
            "id": 199,
            "name": "HeadHunter",
            "type": "system",
            "foreign": "HH"
        }
    ]
}
```

---

## Production Calendar - Get Non-Working Days

Calculates non-working days within a date range based on country-specific production calendars.

```bash
# Get non-working days count between today and deadline
curl -X GET "https://api.huntflow.ru/production_calendar/1/days/2024-12-31?start=2024-01-01&verbose=true" \
  -H "User-Agent: MyApp/1.0 (contact@example.com)" \
  -H "Authorization: Bearer <access_token>"

# Response:
{
    "total_days": 365,
    "not_working_days": 118,
    "items": ["2024-01-01", "2024-01-02", "2024-01-06", "2024-01-07", "..."]
}

# Bulk request for multiple date ranges
curl -X POST "https://api.huntflow.ru/production_calendar/1/days?verbose=false" \
  -H "User-Agent: MyApp/1.0 (contact@example.com)" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '[
    {"deadline": "2024-04-20"},
    {"deadline": "2024-05-20", "start": "2024-04-01"}
  ]'
```

---

## Production Calendar - Calculate Deadline

Calculates a deadline date by adding working days to a start date, accounting for holidays.

```bash
# Get deadline 30 working days from today
curl -X GET "https://api.huntflow.ru/production_calendar/1/deadline/30?start=2024-03-01" \
  -H "User-Agent: MyApp/1.0 (contact@example.com)" \
  -H "Authorization: Bearer <access_token>"

# Response:
"2024-04-15"

# Bulk deadline calculation
curl -X POST "https://api.huntflow.ru/production_calendar/1/deadline" \
  -H "User-Agent: MyApp/1.0 (contact@example.com)" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '[
    {"days": 10},
    {"days": 20},
    {"days": 30, "start": "2024-09-01"}
  ]'

# Response:
{
    "items": ["2024-03-15", "2024-03-29", "2024-10-14"]
}
```

---

## Vacancy Requests - List and Create

Manages vacancy approval requests with customizable schemas and multi-level approval workflows.

```bash
# Get vacancy request schemas
curl -X GET "https://api.huntflow.ru/account/123/account_vacancy_request" \
  -H "User-Agent: MyApp/1.0 (contact@example.com)" \
  -H "Authorization: Bearer <access_token>"

# Create a vacancy request with approval workflow
curl -X POST "https://api.huntflow.ru/account/123/vacancy_request" \
  -H "User-Agent: MyApp/1.0 (contact@example.com)" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "account_vacancy_request": 1,
    "position": "Director",
    "money": "$150000",
    "hard_skills": "10+ years executive leadership experience",
    "soft_skills": "Strategic thinking, team management",
    "comment": "Urgent hire needed",
    "files": [1, 2],
    "attendees": [
        {"email": "ceo@example.com", "displayName": "CEO"},
        {"email": "hr-director@example.com", "displayName": "HR Director"}
    ]
  }'

# Response includes request ID and status
{
    "id": 10,
    "status": "pending",
    "position": "Director",
    "created": "2024-07-10T14:50:21+03:00"
}
```

---

## Webhooks Configuration

Webhooks notify external systems about events in Huntflow. Configure webhooks in company settings to receive POST requests for candidate, vacancy, and offer events.

```bash
# Webhook request headers sent by Huntflow:
# X-Huntflow-Delivery: fcb5de9e-75a9-42c7-a7d2-3f070f2c5e00  (unique ID)
# X-Huntflow-Event: APPLICANT  (event type: APPLICANT, VACANCY, OFFER, PING)
# X-Huntflow-Signature: 298d0211...  (HMAC-SHA256 signature if secret configured)

# Example APPLICANT webhook payload:
{
    "event": {
        "id": 1,
        "type": "STATUS",
        "applicant": {
            "id": 1,
            "first_name": "John",
            "last_name": "Doe",
            "middle_name": "Michael",
            "birthday": "1970-01-01",
            "photo": {"url": "https://store.huntflow.ru/..."}
        },
        "vacancy": {
            "id": 1,
            "position": "Manufacturing Engineer",
            "company": "Tesla",
            "money": "$100k",
            "state": "OPEN"
        },
        "status": {"id": 3, "name": "Declined"},
        "rejection_reason": {"id": 4, "name": "Does not meet qualifications"},
        "created": "2024-08-22T18:16:27+03:00"
    },
    "author": {"id": 4, "name": "David Smith", "email": "smith@example.com"},
    "account": {"id": 6, "name": "San Carlos Recruitment"}
}

# Verify webhook signature in your handler (Python example):
import hmac
import hashlib

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)
```

---

## Error Handling

All API errors return structured JSON responses with error type and description. Applications should handle HTTP status codes appropriately.

```bash
# Example error responses:

# 400 Bad Request - Invalid input
{
    "errors": [
        {"type": "validation.email", "value": ["error.invalid_email"]},
        {"type": "common", "value": ["invalid json"]}
    ]
}

# 401 Unauthorized - Authentication failure
{
    "errors": [
        {"type": "oauth", "value": ["bad_authorization"]}
    ]
}
# Other oauth values: "token_expired", "token_revoked"

# 400 Bad Request - Missing User-Agent header
{
    "errors": [
        {"type": "bad_user_agent", "value": []}
    ]
}

# 429 Too Many Requests - Rate limit exceeded
# (Limit: 10 requests per second per token)

# 500 Internal Server Error
{
    "errors": [
        {"type": "server_error", "value": []}
    ]
}
```

---

## Summary

The Huntflow API v1 provides comprehensive recruitment workflow automation capabilities for building career portals, HR integrations, and applicant tracking solutions. Key use cases include: syncing job postings from internal systems to Huntflow, collecting applications from corporate career sites, automating candidate status updates via webhooks, integrating with HRIS systems for onboarding workflows, and building recruitment analytics dashboards using vacancy and applicant data.

Integration patterns typically involve initial OAuth authentication or personal token setup, followed by organization discovery via `/accounts`, then CRUD operations on vacancies and candidates within the organization context. Webhooks enable event-driven architectures where external systems react to hiring pipeline changes in real-time. The production calendar service helps calculate realistic hiring deadlines accounting for regional holidays. Note that this API version is deprecated - new integrations should use v2 at `https://api.huntflow.ai/v2/docs` which offers improved functionality and continued support.