# HeadHunter — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search and filter job vacancies across hh.ru by salary, experience level, employment type, schedule, work format, region, and industry to find positions that match your criteria. Retrieve detailed information about specific job openings to compare opportunities and make informed career decisions.

**Category:** Jobs | **Website:** [hh.ru/](https://hh.ru/) | **Docs:** [parse.bot/marketplace/010f54ea-6ae2-4e05-904b-156f0a706b28/hh-ru-api](https://parse.bot/marketplace/010f54ea-6ae2-4e05-904b-156f0a706b28/hh-ru-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-hh-ru-api-010f54ea/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_vacancy

Get detailed information about a specific vacancy by its numeric ID. Returns full HTML description, key skills, employer details, salary, address, experience requirement, hiring formats, and labels. The vacancy_id is obtained from search_vacancies results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `vacancy_id` | string | Yes | Vacancy ID (numeric, obtained from search_vacancies results) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-hh-ru-api-010f54ea/get_vacancy \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"vacancy_id":"<string>"}'
```

### search_vacancies

Full-text search over hh.ru vacancies with filters for region, experience, employment type, schedule, salary, and more. Returns paginated results. Each vacancy includes id, title, salary, employer, address, experience, and labels. Pagination is page-based (0-indexed). The total matched count is in `found`; `pages` gives total pages available.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `area` | string | No | Region ID (1=Moscow, 2=St Petersburg). Multiple values supported. |
| `currency` | string | No | Salary currency code: RUR, USD, EUR, KZT, UAH, AZN, UZS, GEL, KGS, BYR |
| `education` | string | No | Education level: not_required_or_not_specified, secondary, special_secondary, higher, bachelor, master, candidate, doctor |
| `employer_id` | string | No | Employer/company ID |
| `employment` | string | No | Employment type: full, part, project, volunteer, probation |
| `enable_snippets` | string | No | Enable text snippets in results (true/false) |
| `experience` | string | No | Required experience: noExperience, between1And3, between3And6, moreThan6 |
| `industry` | string | No | Industry ID (numeric) |
| `label` | string | No | Labels: with_address, accept_handicapped, accept_kids, not_from_agency, accredited_it, low_performance |
| `only_with_salary` | string | No | Show only vacancies with salary specified (true/false) |
| `order_by` | string | No | Sort order: relevance, publication_time, salary_desc, salary_asc |
| `page` | integer | No | Page number (0-indexed) |
| `per_page` | integer | No | Results per page |
| `professional_role` | string | No | Professional role ID (numeric) |
| `salary` | integer | No | Minimum salary amount |
| `schedule` | string | No | Work schedule: fullDay, shift, flexible, remote, flyInFlyOut |
| `search_field` | string | No | Where to search: name, company_name, description |
| `search_period` | integer | No | Publication period in days: 1, 3, 7, 30 |
| `text` | string | No | Search keywords (e.g. 'python developer', 'data engineer') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-hh-ru-api-010f54ea/search_vacancies \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"area":"<string>","currency":"<string>","education":"<string>","employer_id":"<string>","employment":"<string>","enable_snippets":"<string>","experience":"<string>","industry":"<string>","label":"<string>","only_with_salary":"<string>","order_by":"<string>","page":"<integer>","per_page":"<integer>","professional_role":"<string>","salary":"<integer>","schedule":"<string>","search_field":"<string>","search_period":"<integer>","text":"<string>"}'
```