HelloWork APIhellowork.com ↗
Search French job listings, fetch full job details, look up company profiles, and browse job categories on HelloWork via a structured REST API.
What is the HelloWork API?
The HelloWork API provides 5 endpoints for querying France's HelloWork job board, covering job search, individual listing details, company lookup, company profiles, and category browsing. The search_jobs endpoint accepts keyword, location, contract type, salary, and radius filters and returns paginated arrays of listings with titles, companies, salaries, and direct URLs. Data is returned in structured JSON, ready to pipe into recruiting tools, job aggregators, or market analysis workflows.
curl -X GET 'https://api.parse.bot/scraper/1d40664b-41f0-4fc1-b677-06357ffec8d8/search_jobs?c=CDI&d=h&k=d%C3%A9veloppeur&l=Paris&st=date&msa=30000&ray=20&page_limit=1&filter_hourly=false' \ -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 hellowork-com-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.
"""HelloWork job & company search: search jobs, drill into details, explore companies and categories."""
from parse_apis.HelloWork_Job___Company_Search_API import (
HelloWork, Sort, DateRange, ContractType, NotFound
)
client = HelloWork()
# Search for CDI developer jobs in Paris, sorted by relevance
for job in client.job_summaries.search(
keyword="développeur",
location="Paris",
sort=Sort.RELEVANCE,
contract_type=ContractType.CDI,
date_range=DateRange.MONTH,
limit=5,
):
print(job.title, "|", job.company, "|", job.salary)
# Drill into the first result for the full job description
top_job = client.job_summaries.search(keyword="développeur", location="Paris", limit=1).first()
if top_job:
full = top_job.details()
print(full.title, full.url, full.description[:100])
# Search for a company and fetch its profile
company = client.company_summaries.search(query="acadomia", limit=1).first()
if company:
slug = f"{company.name.lower().replace(' ', '-')}-{company.id}"
profile = client.company_profiles.get(company_slug_id=slug)
print(profile.name, profile.url)
# Browse all job categories
cats = client.category_indexes.get()
print(f"Total categories: {len(cats.categories)}")
# Typed error handling when a company profile doesn't exist
try:
client.company_profiles.get(company_slug_id="nonexistent-99999")
except NotFound as exc:
print(f"Not found: {exc}")
print("exercised: job_summaries.search / details / company_summaries.search / company_profiles.get / category_indexes.get")
Full-text search over job listings on HelloWork France. Supports filters for contract type, location, salary, date range, and sorting. Returns paginated results across multiple pages. Each result includes title, company, location, contract type, salary, and a direct URL.
| Param | Type | Description |
|---|---|---|
| c | string | Contract type filter. For multiple types, comma-separated (e.g. 'CDI,CDD'). |
| d | string | Date range filter. |
| krequired | string | Keyword to search for (job title, skill, etc.) |
| l | string | Location (city, department, postal code) |
| st | string | Sort order. |
| msa | string | Minimum annual salary filter (numeric string, e.g. '40000'). |
| ray | string | Search radius in km around the location. |
| page_limit | integer | Maximum number of pages to fetch (each page has ~30 results). |
| filter_hourly | boolean | If true, filters out jobs with hourly-rate salaries from results. |
{
"type": "object",
"fields": {
"items": "array of job listing objects with id, title, company, location, contract, salary, url"
},
"sample": {
"data": {
"items": [
{
"id": "80049429",
"url": "https://www.hellowork.com/fr-fr/emplois/80049429.html",
"title": "Assistant de Direction Pole Business Dev H/F",
"salary": "50 000 - 60 000 € / an",
"company": "Skills Paris",
"contract": "Intérim",
"location": "Paris 8e - 75"
}
]
},
"status": "success"
}
}About the HelloWork API
Job Search and Listing Details
The search_jobs endpoint accepts a required k keyword parameter plus optional filters: c for contract type (e.g. CDI, CDD, comma-separated for multiple), l for location (city, department, or postal code), ray for radius in km, msa for minimum annual salary, d for date range, and st for sort order. Results are paginated at roughly 30 listings per page; use page_limit to cap how many pages are fetched. Each item in the returned items array includes id, title, company, location, contract, salary, and url.
To retrieve the complete description and structured metadata for a listing, pass its numeric id to get_job_details. The response returns a data object with id, title, description (full text), details (location, contract type, and other structured metadata), and the canonical url. Job IDs come directly from search_jobs results.
Company Search and Profiles
search_companies takes a query string and an optional l location filter, returning an items array of objects with id and name. These IDs feed into get_company_profile, which expects a company_slug_id in the format lowercase-hyphenated-name-id (e.g. capgemini-6026). The profile response includes name, profile_data (description, workplace highlights, a verbatim quote), the count of active job offers, and the page url.
Job Categories
get_job_categories requires no parameters and returns a categories object mapping display names (French métier labels) to their relative URL paths on HelloWork. This is useful for building category-driven browsing interfaces or for discovering the valid taxonomy before running targeted keyword searches.
The HelloWork API is a managed, monitored endpoint for hellowork.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when hellowork.com 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 hellowork.com 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 French job listings filtered by contract type and minimum salary for a compensation benchmarking dataset
- Monitor new CDI postings in a specific city by polling search_jobs with location and date range filters
- Build a company research tool that pulls HelloWork profile data including active job counts and workplace highlights
- Enrich an ATS or recruiting CRM with full job descriptions fetched via get_job_details using IDs from search
- Map job category taxonomy from get_job_categories to normalize listings from multiple French job boards
- Track how many open roles a specific company has over time using get_company_profile's active offers count
- Power a French job board aggregator that surfaces listings with salary, location, and contract type in one response
| 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 HelloWork have an official developer API?+
What contract types can I filter by in search_jobs?+
c parameter accepts French contract type codes such as CDI (permanent) and CDD (fixed-term). You can pass multiple types as a comma-separated string (e.g. CDI,CDD). The response labels each listing's contract field with the type found in the listing itself.How does pagination work in search_jobs, and what is the practical limit?+
page_limit parameter controls the maximum number of pages fetched in a single call. For broad keyword searches, setting a low page_limit keeps response times predictable; omitting it allows the endpoint to fetch all available pages, which can be substantial for common terms.