GuidesAPI EndpointsAPI Changelog
Live AI Demo
API Changelog
Added

Searching API now filters profiles and jobs by range, with histograms

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_float or ranges_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/scoring and GET /profiles/matching filter profiles on the ranges of their Sources: ranges_number for number ranges and ranges_date for date ranges. Each is a list of {"name", "value_min", "value_max"}, with null for an open end. GET /jobs/searching, GET /jobs/scoring and GET /jobs/matching take the same filters on the ranges of their Boards, next to ranges_float.
  • facets=["ranges"] on GET /profiles/searching and GET /jobs/searching returns a histogram of each range: numbers in meta.numeric_facets, in bins of equal width with their min, max and count; dates in meta.date_facets, in calendar bins (days, weeks, months, years…) with their start and count. A bin's count is 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_float and ranges_date on 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_min is open above: it overlaps every requested range that ends at or above that minimum; a range with only value_max is open below. A range with neither bound, or whose value_min is above its value_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:00 or +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.

Links