boss APIboss.az ↗
Access boss.az job vacancies, company profiles, categories, and regions via 5 endpoints. Filter by salary, location, and category. Includes contact emails and phones.
What is the boss API?
The boss.az API provides access to Azerbaijan's leading job board through 5 endpoints covering vacancy search, full vacancy details, company profiles, job categories, and regional data. The search_vacancies endpoint accepts keyword, salary range, category, and region filters, returning paginated results with contact emails and phone numbers directly from each posting. Company profile lookups are available via get_company_profile using IDs surfaced in vacancy results.
curl -X GET 'https://api.parse.bot/scraper/cfd9cc2f-27e9-45aa-955b-64d969d76000/search_vacancies?limit=5®ion_ids=1&salary_max=5000&salary_min=500&search_term=manager&category_ids=37&education_ids=%5B%5D&experience_ids=%5B%5D' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace boss-az-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: boss.az job board SDK — search vacancies, drill into details, explore companies."""
from parse_apis.boss_az_job_board_api import BossAz, ResourceNotFound
client = BossAz()
# List all regions to find valid IDs for filtering
for region in client.regions.list(limit=5):
print(region.id, region.name)
# Search vacancies with a keyword, capped at 3 results
vacancy = client.vacancies.search(search_term="manager", limit=1).first()
if vacancy:
print(vacancy.position_name, vacancy.location, vacancy.salary_from, vacancy.salary_to)
# Drill into the company via the profile reference
company = client.companies.get(id=vacancy.profile.id)
print(company.name, company.contact_name, company.published_count)
# Browse job categories (single-page list)
for cat in client.categories.list(limit=3):
print(cat.name, [child.name for child in cat.children[:2]])
# Typed error handling for a non-existent vacancy
try:
client.vacancies.get(id="999999999")
except ResourceNotFound as exc:
print(f"Not found: {exc}")
print("exercised: regions.list / vacancies.search / vacancies.get / companies.get / categories.list")
Search for job vacancies with optional filters including keyword, category, region, salary range, education, and experience. Returns paginated results with contact info (email, phones). Paginates via cursor (endCursor). Each vacancy carries a profile sub-object linking to the employer company.
| Param | Type | Description |
|---|---|---|
| after | string | Cursor for pagination, use endCursor from a previous response. |
| limit | integer | Number of results to return per page. |
| region_ids | string | JSON array of region/city IDs to filter by (e.g. "[1,4]"). IDs available from get_all_regions. |
| salary_max | integer | Maximum salary filter. |
| salary_min | integer | Minimum salary filter. |
| search_term | string | Keyword to search for in vacancy listings. |
| category_ids | string | JSON array of job category IDs to filter by (e.g. "[37,38]"). IDs available from get_all_categories. |
| education_ids | string | JSON array of education level IDs to filter by. |
| experience_ids | string | JSON array of experience level IDs to filter by. |
{
"type": "object",
"fields": {
"nodes": "array of vacancy objects with id, positionName, name, location, salaryFrom, salaryTo, email, phones, description, requirements, responsibilities, education, experience, and profile",
"endCursor": "string cursor for fetching the next page",
"totalCount": "integer total number of matching vacancies",
"hasNextPage": "boolean indicating if more results are available"
},
"sample": {
"data": {
"nodes": [
{
"id": "268973",
"name": "Innova Technology Center",
"email": "[email protected]",
"phones": [
"(051) 240-05-22"
],
"profile": {
"id": "82315",
"name": "Innova Technology Center"
},
"location": "Bakı",
"salaryTo": 2000,
"education": "Ali",
"experience": "3 ildən 5 ilə qədər",
"salaryFrom": 1000,
"description": "<p>Job description HTML</p>",
"positionName": "Sales/Account Manager",
"requirements": "<p>Requirements HTML</p>",
"responsibilities": ""
}
],
"endCursor": "NQ",
"totalCount": 7,
"hasNextPage": true
},
"status": "success"
}
}About the boss API
Vacancy Search and Details
The search_vacancies endpoint accepts up to eight filter parameters including search_term, salary_min, salary_max, category_ids (JSON array), region_ids (JSON array), and education_ids. Results are paginated via cursor — pass the endCursor from one response as the after parameter in the next call. Each vacancy node returns positionName, location, salaryFrom, salaryTo, email, phones, description, requirements, and a profile sub-object carrying the employer's company id and name. The totalCount and hasNextPage fields support building full result sets.
For deeper detail on a single posting, get_vacancy_details takes a numeric vacancy id and returns the full record including education, experience, HTML-formatted description, and salary bounds. The profile sub-object again links to the parent company.
Company Profiles
get_company_profile accepts a numeric company id — available from any vacancy's profile.id field — and returns the company's name, contactName, description, regionName, logoUrl, email, phones, and publishedCount (the number of currently active listings). This makes it straightforward to enrich a list of vacancies with employer context without additional search calls.
Reference Data: Categories and Regions
Two lookup endpoints require no input parameters. get_all_categories returns a flat array of top-level category objects, each with an id, name, parentId, and a children array of subcategories — providing the valid category_ids values for vacancy filtering. get_all_regions returns region objects with numeric id and name fields, supplying valid region_ids for geographic filtering of vacancy searches.
The boss API is a managed, monitored endpoint for boss.az — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when boss.az changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official boss.az API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Aggregate Azerbaijani job listings filtered by category and region into a localized job board
- Monitor salary ranges across industries using salaryFrom and salaryTo fields from search_vacancies
- Build a company directory from get_company_profile data including contact names, emails, and active listing counts
- Track hiring activity for specific employers by polling publishedCount from get_company_profile over time
- Enrich CRM or lead-gen pipelines with employer contact details (email, phones) extracted from vacancy results
- Power a job alert system using keyword and category filters in search_vacancies with cursor-based pagination
- Map job availability by region using region IDs from get_all_regions combined with vacancy search results
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does boss.az offer an official developer API?+
How does pagination work in search_vacancies?+
endCursor string and a hasNextPage boolean. To fetch the next page, pass the endCursor value as the after parameter in your next request. The totalCount field tells you the total number of matching vacancies across all pages.What contact information is returned for vacancies?+
search_vacancies and get_vacancy_details endpoints both return email and phones (an array of strings) directly on the vacancy object. get_company_profile also returns email, phones, and a contactName field at the company level.Does the API return resume or applicant data?+
Are subcategories available for filtering, or only top-level categories?+
get_all_categories returns both top-level categories and their subcategories. Each top-level object includes a children array of subcategory objects, each with its own id. You can pass any of those subcategory IDs inside the category_ids JSON array when calling search_vacancies to filter at the subcategory level.