HeadHunter API Client

A TypeScript client for the HeadHunter API, generated from the official OpenAPI specification.

Features

• 🔥 TypeScript first - Full type safety with generated types
• 🚀 Modern SDK - Built with @hey-api/openapi-ts
• 📝 Complete API coverage - All HeadHunter API endpoints
• 🛡️ Built-in validation - Request/response validation
• 🎯 Tree-shakeable - Import only what you need
• 📚 Well documented - JSDoc comments for all methods

Installation

npm install @sargonpiraev/hh-api-client

Get Your Credentials

Before installation, you'll need HeadHunter API credentials:

1. Visit HeadHunter Developer Portal
2. Create an application to get client credentials
3. For authenticated requests, implement OAuth flow to get access token
4. Set up proper User-Agent format: "AppName/Version ([email protected])"

Requirements

• Node.js >= v18.0.0
• HeadHunter API credentials (User-Agent required, access token optional)
• npm >= 8.0.0

Quick Start

import { createHeadHunterClient, getVacancies, getAreas, type GetVacanciesData } from '@sargonpiraev/hh-api-client'

// Create a configured client
const client = createHeadHunterClient({
  userAgent: 'MyApp/1.0.0 ([email protected])',
  accessToken: 'your-access-token', // optional
})

// Search for vacancies
const searchParams: GetVacanciesData = {
  query: {
    text: 'JavaScript developer',
    area: '1', // Moscow
    per_page: 50,
  },
}

const vacancies = await getVacancies({
  client,
  ...searchParams,
})

console.log(`Found ${vacancies.data.found} vacancies`)

// Get dictionaries
const areas = await getAreas({ client })
console.log('Available areas:', areas.data)

Usage Examples

Search Vacancies

import { getVacancies, type GetVacanciesData } from '@sargonpiraev/hh-api-client'

const searchParams: GetVacanciesData = {
  query: {
    text: 'Frontend Developer',
    area: '1', // Moscow
    professional_role: '96', // Developer role
    experience: 'between1And3',
    employment: 'full',
    schedule: 'remote',
    salary_from: 100000,
    currency: 'RUR',
    only_with_salary: true,
  },
}

const result = await getVacancies({ client, ...searchParams })

Get Vacancy Details

import { getVacancy } from '@sargonpiraev/hh-api-client'

const vacancy = await getVacancy({
  client,
  path: { vacancy_id: '12345' },
})

console.log(vacancy.data.name)
console.log(vacancy.data.description)

Apply to Vacancy

import { applyToVacancy } from '@sargonpiraev/hh-api-client'

await applyToVacancy({
  client,
  path: { vacancy_id: '12345' },
  body: {
    resume_id: 'resume-id',
    message: 'I am interested in this position...',
  },
})

Work with Dictionaries

import { getAreas, getIndustries, getSkills, getProfessionalRolesDictionary } from '@sargonpiraev/hh-api-client'

// Get all areas (cities/regions)
const areas = await getAreas({ client })

// Get industries
const industries = await getIndustries({ client })

// Get skills
const skills = await getSkills({ client })

// Get professional roles
const roles = await getProfessionalRolesDictionary({ client })

User Information

import { getCurrentUserInfo, editCurrentUserInfo } from '@sargonpiraev/hh-api-client'

// Get current user info
const user = await getCurrentUserInfo({ client })

// Update user info
await editCurrentUserInfo({
  client,
  body: {
    first_name: 'John',
    last_name: 'Doe',
    email: '[email protected]',
  },
})

Configuration

Required User-Agent

HeadHunter API requires a specific User-Agent format:

ApplicationName/Version ([email protected])

Example:

const client = createHeadHunterClient({
  userAgent: 'JobSearchApp/1.0.0 ([email protected])',
})

Authentication

For protected endpoints, provide an access token:

const client = createHeadHunterClient({
  userAgent: 'MyApp/1.0.0 ([email protected])',
  accessToken: 'your-oauth-token',
})

Custom Base URL

For testing or custom environments:

const client = createHeadHunterClient({
  userAgent: 'MyApp/1.0.0 ([email protected])',
  baseURL: 'https://api.hh.ru', // default
})

API Reference

Most Used Functions

• getVacancies() - Search vacancies
• getVacancy() - Get vacancy details
• getAreas() - Get areas/cities
• getIndustries() - Get industries
• getCurrentUserInfo() - Get user info
• applyToVacancy() - Apply to vacancy

All Available Functions

The client exports all generated SDK functions. See the HeadHunter API documentation for complete reference.

// Import everything
import * as HHApi from '@sargonpiraev/hh-api-client'

// Or import specific functions
import {
  getVacancies,
  getNegotiations,
  createResume,
  // ... etc
} from '@sargonpiraev/hh-api-client'

TypeScript Support

Full TypeScript support with generated types:

import type { GetVacanciesData, GetVacanciesResponses, Vacancy, Area, Industry } from '@sargonpiraev/hh-api-client'

const handleVacancy = (vacancy: Vacancy) => {
  console.log(vacancy.name)
  console.log(vacancy.salary?.from)
}

Error Handling

try {
  const result = await getVacancies({ client, query: { text: 'Developer' } })
  console.log(result.data)
} catch (error) {
  if (error.status === 400) {
    console.error('Bad request:', error.data)
  } else if (error.status === 403) {
    console.error('Forbidden:', error.data)
  } else {
    console.error('Unexpected error:', error)
  }
}

Roadmap

Coming Soon 🚀

• [ ] Enhanced Type Safety: Additional validation and type guards
• [ ] Response Caching: Intelligent caching for frequently accessed data
• [ ] Batch Operations: Support for bulk API operations
• [ ] Rate Limiting: Built-in rate limiting and retry logic
• [ ] Offline Support: Offline-first capabilities with sync
• [ ] React Hooks: React hooks package for easier integration

Completed ✅

• [x] Full API Coverage: Complete HeadHunter API integration
• [x] Type Generation: Automated TypeScript types from OpenAPI
• [x] Error Handling: Comprehensive error management
• [x] Tree Shaking: Optimized bundle size with selective imports

Community Requests 💭

Have an idea for HeadHunter API Client? Open an issue or contribute to our roadmap!

Support This Project

Hi! I'm Sargon Piraev, a software engineer passionate about API integrations and developer tools. I create open-source API clients to help developers integrate with their favorite services more easily.

Your support helps me continue developing and maintaining these tools, and motivates me to create new integrations that make developer workflows even more efficient! 🚀

Connect with Author

• 🌐 Visit sargonpiraev.com
• 📧 Email: [email protected]
• 💼 LinkedIn: linkedin.com/in/sargonpiraev