# HeadHunter — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.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 for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/headhunter/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## 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.beta.paywithlocus.com/api/wrapped/credits/headhunter/get-vacancy \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/headhunter/search-vacancies \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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>"}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.