Added
Searching API now filters profiles and jobs by range, with histograms
9 days ago by ReadMe API
Profiles and jobs can now be filtered on any range of their Sources and Boards, and facets=["ranges"] returns a histogram of each range whose bars count exactly what a filter on them returns. A search screen can show how candidates or jobs spread before a recruiter picks a band.
Action required
- Now: none. Every endpoint keeps its parameters and its response shape. If you filter jobs with
ranges_floatorranges_date, check the results you rely on: a job now comes back when its range overlaps yours, even partly. - Later: none. Nothing in this update is deprecated.
What changed
GET /profiles/searching,GET /profiles/scoringandGET /profiles/matchingfilter profiles on the ranges of their Sources:ranges_numberfor number ranges andranges_datefor date ranges. Each is a list of{"name", "value_min", "value_max"}, withnullfor an open end.GET /jobs/searching,GET /jobs/scoringandGET /jobs/matchingtake the same filters on the ranges of their Boards, next toranges_float.facets=["ranges"]onGET /profiles/searchingandGET /jobs/searchingreturns a histogram of each range: numbers inmeta.numeric_facets, in bins of equal width with theirmin,maxandcount; dates inmeta.date_facets, in calendar bins (days, weeks, months, years…) with their start andcount. A bin'scountis the number of items a filter on that bin returns, with the filters of the request, its own range's included: to keep a range's whole spread on screen while a band is picked, ask for its histogram without that band.- A range filter matches an item when one of the item's ranges of that name overlaps the requested range, even partly. Ranges of different names must all match, and several ranges of one name are alternatives: two ranges narrow the results, two bands of one range widen them. This holds for
ranges_floatandranges_dateon jobs too, so a job filter can now return more jobs, or fewer when it names several ranges. Add"relation": "within"to a range to keep only the items whose range lies inside it, or"relation": "contain"for those whose range covers it. - A range with only
value_minis open above: it overlaps every requested range that ends at or above that minimum; a range with onlyvalue_maxis open below. A range with neither bound, or whosevalue_minis above itsvalue_max, is left out of filters and histograms, and the rest of the profile or job stays searchable. To store an exact value, send it as both bounds. - Date bounds are read with or without a colon in their offset (
+00:00or+0000), in filters and in the ranges of the profiles and jobs indexed or updated since 13 November.
Example
A search screen that lets a recruiter pick an expected salary band and an availability month, on a Source whose profiles hold an Expected salary range and an Availability range:
# 1. The histograms of the ranges of a Source
curl -G https://api.hrflow.ai/v1/profiles/searching \
-H "X-API-KEY: <your_api_key>" \
-H "X-USER-EMAIL: <your_email>" \
--data-urlencode 'source_keys=["<source_key>"]' \
--data-urlencode 'facets=["ranges"]'
# 2. The profiles of the band a recruiter picks
curl -G https://api.hrflow.ai/v1/profiles/searching \
-H "X-API-KEY: <your_api_key>" \
-H "X-USER-EMAIL: <your_email>" \
--data-urlencode 'source_keys=["<source_key>"]' \
--data-urlencode 'ranges_number=[{"name": "Expected salary", "value_min": 45000, "value_max": 55000}]' \
--data-urlencode 'ranges_date=[{"name": "Availability", "value_min": "2027-01-01T00:00:00Z", "value_max": "2027-01-31T23:59:59Z"}]'The first request answers with counts under meta and no profiles, as facets does. An excerpt:
{
"code": 200,
"message": "Profile searching results",
"meta": {
"total": 42,
"numeric_facets": {
"Expected salary": {"min": 30000, "max": 80000, "count": 38, "buckets": [
{"min": 30000, "max": 35000, "count": 2},
{"min": 35000, "max": 40000, "count": 5},
{"min": 40000, "max": 45000, "count": 9}
]}
},
"date_facets": {
"Availability": {"interval": "1M", "buckets": [
{"key": 1796083200000, "key_as_string": "2026-12-01T00:00:00Z", "count": 21},
{"key": 1798761600000, "key_as_string": "2027-01-01T00:00:00Z", "count": 27}
]}
}
},
"data": {"profiles": []}
}The second returns, in data.profiles, the profiles whose expected salary range overlaps the 45–55 k€ band and who are available in January.