Skip to main content

Building a Natural Language Search & Score Experience

Build a smart search bar using HrFlow.ai APIs to parse queries, enrich jobs, and rank profiles from your talent pool in real time.

T
Written by Thomas Zhu
Updated today

Creating a smart profile search bar allows users to turn natural language queries into powerful AI-driven searches across your talent pool. By leveraging HrFlow.ai’s Scoring and Parsing APIs, you can build a fully automated system that translates user intent into structured job queries and ranks relevant candidates in real time.

This guide walks you through setting up the necessary infrastructure, processing user inputs, and retrieving ranked results using HrFlow.ai APIs.

The profile search bar combines several HrFlow.ai capabilities:

  • Text Parsing API — to parse free-text queries into structured Job objects

  • Geocoding API — to enrich detected locations with latitude and longitude

  • Asking API — to extract advanced filtering criteria such as experience level

  • Scoring API — to rank profiles from your talent pool against the structured query

🔎 Guide Overview

Step 1 – Extract the User Query in a Standard format

Start by capturing the user’s input through a simple search field. For example:

"I am looking for a Data Scientist with 3 years of experience in deep learning and located in Paris."

Send this text to the Text Parsing API using the following parameters:

  • parsing_model: "atlas"

  • output_object: "job"

This returns a structured Job object in HrFlow.ai format, which captures key elements like job title, skills, experience, and location.

If the returned object includes a location (e.g., "location.text": "Paris"), use the Geocoding API to resolve it into geographic coordinates (lat, lng). This allows more accurate filtering later based on distance.

You can also enrich the Job with context from the UI (e.g. remote preference, contract type) before indexing it.

📘 API Reference:

Step 2 – Index the Query as a Job

Once the Job is enriched, you need to index it in a HrFlow.ai Board using the Job Indexing API. This step is essential as it persists the Job and enables the use of advanced APIs like Asking and Scoring.

The Job acts as a query anchor: it represents the user's intent and will be used to evaluate the relevance of candidate profiles.

📌 Make sure:

  • The target Board has both Scoring and Searching enabled.

  • You're using a clean, dedicated board for search queries (if needed).

🔒 Requirements:

  • A Board of Jobs to store the structured queries generated from the search bar.

    • This board will serve as the container for all search queries represented as Job objects.

    • ⚠️ Both Searching and Scoring must be enabled for this board.

📘 API Reference:

Step 3 – Enrich the Query with Further Criteria

To improve the precision of your search, you can use the Asking API to extract high-level filtering criteria from the Job. The Asking API answers targeted questions such as:

"What is the required experience level?"
"What education level is needed?"
"Is this a full-time or part-time role?"

While the information may already exist in the job description, Asking provides normalized and explicit answers, which you can then format into tags like this:

{ 
    "tags": [ 
        {"name": "experience_level", "value": "3 years"}, 
        {"name": "education_level", "value": "master"}, 
        {"name": "contract_type", "value": "full-time"}, 
    ] 
}

Use the Edit Job API to update the indexed Job with these tags.

ℹ️ These tags are not used for job search, but are critical for filtering during profile scoring.

📘 API Reference:

Step 4 – Score Profiles with the Built Query

With your structured and enriched Job object ready, you can now use the Score Profiles for a Job endpoint to retrieve and rank profiles from a specific source.

The API compares the content of the Job with candidate profiles and returns a ranked list of profiles based on relevance.

Required parameters:

  • algorithm_key (string) — The key of the scoring algorithm to use

  • source_keys (string array) — The list of profile source keys to score against (e.g., ["source_1", "source_2"])

  • board_key (string) — The key of the board where the Job is indexed

  • job_key (string) — The unique identifier of the Job object

Filtering Parameters:

  • tags_included: filter profiles by structured tags (e.g., experience level, contract type)

  • location_geopoint + location_distance: restrict profiles to a geographic area

  • skills, languages: additional refinement options

  • limit, page: pagination controls

The response contains an array of profiles, each paired with a prediction score that represents how well it matches the Job.

Use this ranked list to power your search results UI and surface the most relevant candidates to users—efficiently and intelligently.

🔒 Requirements:

  • A Source of Profiles that the search bar will return results from.

    • This source should be actively indexed with candidate profiles.

    • ⚠️ Ensure that both Searching and Scoring features are enabled for the source.

  • A Scoring Algorithm to score profiles against a Job

    • the algorithm_key corresponds to an available scoring algorithm in your HrFlow.ai environment

    • This key determines the model logic used to compute relevance between the Job and Profiles

💡 For the full list of available filtering options, refer to the official documentation.

📘 API Reference:

Conclusion

With the backend in place, you can now focus on building a clean and responsive UI to deliver your smart search experience.

Your interface should:

  • Include a free-text search bar for user queries

  • Display ranked profile results with key info and relevance indicators

  • Handle loading states, pagination, and empty results gracefully

This UI will turn complex candidate searches into a fast, intuitive experience powered by HrFlow.ai’s intelligent Scoring pipeline.

Did this answer your question?