Profiles Searching

A complete guide on how to use Profiles Searching


In this topic, we'll take a look at how the profile search API works by understanding its main components, outline what it takes to get up and running with it, and then interact with the endpoint by testing queries via our public Postman collection. The final goal is to allow you to seamlessly integrate into your website structure to deliver fast and personalized profile search experiences.

To begin, we will start by looking at how to set up the necessary technical prerequisites for using this functionality, with a simple use-case illustration. Next, we'll look at how to use our API to get results from a search with criteria, and finally we'll present an example that showcases how we can design a complete custom profile search experience that can be integrated into real pages on your website.

At the end of the day, the goal is to equip you with the practical tools to build a fully functional profile search using

What you need to get your hands on Profiles Searching



  1. ✨ Create a Workspace
  2. 🔑 Get your API Key
  3. 🧠 Activate Profiles Searching API
  4. 🔌 Create a Source
  5. 💾 Index Profiles in the Source
  6. Create a Postman account and Fork Collection

Profiles Searching Setup

You can break down how to implement Profiles Searching into four steps:

Step 1: Create your Sources

Profiles in are indexed in special folders called Sources. If you don't have a Source created yet, you should refer to this page 🔌 Create a Source to create your Source.
If you are dealing with data coming from multiple origins, creating multiple Sources is the best way to organize the data in

In the following example, we would like to create two Sources to index employees Profiles and interns Profiles :

Connections > My Sources (profiles)Connections > My Sources (profiles)

Connections > My Sources (profiles)

Step 2: Index Profiles in your Sources

To index the Profiles in, we can proceed in two different ways:

  • From structured information
    In case of a Profile with structured information available, in this case a first step of adaptation to the HrFlow format is required in order to create the indexing object from the structured information and using the indexing endpoint the Profile is directly indexed in the source.

You can find here an example of 📖 Profile Object, with required fields and values structure.

  • From a resume file
    If your Profile is an unstructured document (typically a raw resume document), make sure to parse it first (see how 🧠 Parse a Resume in a Source). The Parsing module allows structuring the CV and to automatically index it afterwards in the specified Source.


Index Profile with a reference

To simplify Profile updating in, consider specifying a reference when indexing it.

The reference you use when indexing the Profile will identify it in (along with the Job key).

The reference is not mandatory, if it is not provided, however the Profile will have a unique identification key generated by during the indexing.

Step 3: Add Custom Attributes

You can add custom attributes to further adapt the Profile to your business needs.

  • Tags : are custom attributes uniquely identified by name and value, where the name is the name of the new field to add, and the value is its value.

Here is an example that shows how to add two additional custom fields contract_type and entity as tags in the original Profile object.

  "tags": [{"name": "contract_type", "value": "Full Time"},
          {"name": "entity", "value": "R&D"}], ...}


Make sure that indexed Profiles in remains up-to-date

To ensure that the data indexed in and which will be searched is always the latest updated version of the data, it is necessary to update all Profiles on which changes have taken place using their reference and the corresponding Source key.
Check here for more details on how to 💾 Edit a Profile indexed in a Source.

Let's see what the Profiles Searching API can offer you

Once the Profiles are indexed in the corresponding sources, we can then use the Searching API to make a multi-criteria query search. This search query can be applied to Profiles in one or multiple Sources.

In order to get our hands on the Profiles Searching search endpoint, we are going to use our Postman Collection, in particular the endpoint that allows us to 🧠 Search Profiles indexed in Sources, to get a sense of what kind of data it returns.

Run in PostmanRun in Postman

Don't hesitate to check our publication on Postman to help you get started quickly with our Postman collection.

Configure and setup the Postman environment

Once you have followed the first steps described in this article, you will land on this page :

What you first need to do is to fill the Empty - Environment template that is already provided with the right values

You can fill in only the variables that you will need for Profiles Searching, which are :

  • x-api-key
  • x-user-email
  • source_key : a Source where you will search for the Profiles

Once the values are filled and the Environment is saved, make sure that you select it as your current environment.

Search Profiles in a Source using multiple criteria

Now that the environment is selected, we can try our first request to Search Profiles in the specified Source by source_key , let's try a default request :


Retrieving query results with pagination

Pagination enables you to have full control over the way you retrieve query results.
You can fetch a specific page by using the page parameter which serves as a page offset combined with the limit parameter that specifies the number of profiles per page.
It is recommended not to use large values for the limit parameter and instead rely on the pagination to retrieve all the query results.

Now let's add two filters :

  • Seniority : by specifying experiences_duration_min = 4
  • Skills : looking for profiles with Python skills by setting it in the field skills , which is a list of objects, see for more details.

Notice that the total number of hits returned matches only one profile in our source (which had a total of 2 profiles).

Please refer to 🧠 Search Profiles indexed in Sources, to see the query structure and all the different criteria that can be used to filter the Profiles in the selected Sources.

Search Profiles indexed in multiple Sources using multiple criteria

Now if we want to extend the previous filters, to search Profiles in both employees and Interns Sources, we can simply :
1. Add its source_key to the list of source_keys
2. Send the request and see the new retrieved hits

How can you try Profiles Searching in your own programming language

Now that the request has been tested on Postman, you might want to try the same experience in your favorite programming language.
Luckily for us, Postman can automatically provide us with the right code corresponding to the request in several different programming languages.

All you have to do is :
1. Go to the code tab in the upper right corner,
2. Then select your target programming language from the dropdown,

And voilà, all you have to do now is copy and paste this code and try it out straight away

How to display Profiles Searching results ?

The overall setup can be integrated in one place where multi-criteria filters can be set by the user and the Profiles Searching endpoint is called with the underlying query and the returned results are then displayed in a more user-friendly format.

Here is an example using Plain HTML, Plain CSS and Vanilla Javascript to retrieve Profiles from our Searching API and display results on a page.


In which order results can be displayed ?

The profiles produced by a search query can be displayed in an order (descending order_by = desc or ascending order_by = asc) according to the sort_by parameter specified in the query. This sort parameter can be anything from the date of creation sort_by = created_at of the profile to the compliance of the profile with the criteria sort_by = searching.
The different values allowed for this parameter are listed in detail in 🧠 Search Profiles indexed in Sources

Did this page help you?