Vue d'ensemble des filtres

Les endpoints de recherche de Pubrio (/companies/search, /people/search, /companies/advertisements/search) partagent un moteur de filtres unique. Vous composez un corps de requête une seule fois et les mêmes règles s’appliquent à tous les endpoints — y compris la façon dont les filtres à valeurs multiples se combinent, la façon dont les lieux sont mis en correspondance, et la façon dont vous remplacez l’opérateur par défaut avec filter_conditions.

Pourquoi un moteur de filtres unifié ?

Un seul schéma, trois endpoints

Les filtres au niveau entreprise comme technologies, verticals et founded_dates fonctionnent de façon identique sur /companies/search, /people/search, et à l’intérieur des company_filters des Monitors — vous les apprenez une seule fois.

AND/OR par filtre

La valeur par défaut est OR (correspond à au moins un). Passez des filtres individuels en AND (correspond à tous) en ajoutant une seule entrée à filter_conditions — sans toucher au reste du corps de la requête.

Filtré avant la pagination

Chaque filtre est appliqué avant le renvoi des résultats, de sorte que chaque page et chaque total reflètent l’ensemble de votre requête. Aucun post-filtrage côté application.

Mêmes filtres dans les Monitors

Le bloc company_filters des Monitors accepte la même structure, de sorte qu’un payload de recherche fonctionnel est également un payload de monitor fonctionnel.

Anatomie d’une requête de recherche

Chaque requête de recherche est construite à partir de trois couches dans le même corps JSON :

Couche	Où elle se trouve	Exemples
Filtres personnes	clés de premier niveau	`people_titles`, `management_levels`, `departments`, `people_locations`
Filtres entreprise	imbriqués sous `company_filters: {...}` (recommandé) — également accepté au premier niveau	`technologies`, `verticals`, `founded_dates`, `employees`, `company_locations`
Remplacements d’opérateur	tableau `filter_conditions` (à l’intérieur de `company_filters` lors du remplacement de clés entreprise)	`[{ "key": "technologies", "operator": "and" }]`

Une requête /people/search minimale utilisant les trois couches :

curl -X POST https://api.pubrio.com/people/search \
  -H "Content-Type: application/json" \
  -H "pubrio-api-key: YOUR_API_KEY" \
  -d '{
    "people_titles": ["VP of Engineering", "CTO"],
    "company_filters": {
      "technologies": ["Kubernetes", "Docker"],
      "is_enable_similarity_search": true,
      "company_locations": ["US"]
    },
    "per_page": 25,
    "page": 1
  }'

import requests

response = requests.post(
    "https://api.pubrio.com/people/search",
    headers={
        "Content-Type": "application/json",
        "pubrio-api-key": "YOUR_API_KEY",
    },
    json={
        "people_titles": ["VP of Engineering", "CTO"],
        "company_filters": {
            "technologies": ["Kubernetes", "Docker"],
            "is_enable_similarity_search": True,
            "company_locations": ["US"],
        },
        "per_page": 25,
        "page": 1,
    },
)
print(response.json())

const response = await fetch("https://api.pubrio.com/people/search", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "pubrio-api-key": "YOUR_API_KEY",
  },
  body: JSON.stringify({
    people_titles: ["VP of Engineering", "CTO"],
    company_filters: {
      technologies: ["Kubernetes", "Docker"],
      is_enable_similarity_search: true,
      company_locations: ["US"],
    },
    per_page: 25,
    page: 1,
  }),
});
console.log(await response.json());

`company_filters` : regrouper les clés au niveau entreprise

L’objet enveloppant company_filters: {...} est la façon recommandée d’envoyer les filtres au niveau entreprise — il sépare visuellement les clés qui filtrent la personne de celles qui filtrent l’entreprise, et correspond à la structure déjà utilisée par les Monitors, de sorte que les payloads se transfèrent proprement entre les configurations de recherche et de monitor. Les deux styles fonctionnent ; le moteur aplatit la forme enveloppée au premier niveau avant traitement, et les clés de premier niveau l’emportent en cas de conflit :

{
  "people_titles": ["VP of Engineering"],
  "company_filters": {
    "technologies": [10191, 121],
    "founded_dates": [2015, 2023],
    "company_locations": ["US"]
  }
}

{
  "people_titles": ["VP of Engineering"],
  "technologies": [10191, 121],
  "founded_dates": [2015, 2023],
  "company_locations": ["US"]
}

Lorsque vous ajoutez un remplacement filter_conditions pour une clé au niveau entreprise, placez-le à l’intérieur de company_filters afin qu’il voyage avec les clés qu’il remplace.

Même structure sur les variantes `/search/similar`

POST /companies/search/similar et POST /people/search/similar acceptent le même corps de filtres que leurs équivalents non « similar » (y compris l’enveloppe company_filters et filter_conditions). Chacun ajoute une étape de similarité par-dessus :

	Ce qu’ils nécessitent en plus	Ce que vous obtenez en plus
`/companies/search/similar`	Une entreprise de référence — `domain_search_id`, `domain`, ou `linkedin_url`	Chaque résultat obtient un `similarity_score` (float, 0-1)
`/people/search/similar`	Une personne/un titre de référence — l’un de `people_titles`, `people_search_id`, `linkedin_url`, `linkedin_urls`, ou `peoples`	Les personnes les plus proches de votre référence — Chaque résultat obtient un `similarity_score` (float, 0-1)

Les filtres réduisent le vivier de candidats avant l’application de la similarité — combiner company_locations: ["US"] avec /people/search/similar renvoie donc les personnes basées aux États-Unis les plus proches de vos titres de référence, ce qui correspond au schéma « trouver plus de personnes comme X dans ces contraintes ».

/companies/search/similar renvoie data sous la forme d’un simple tableau d’entreprises — il n’y a pas d’objet pagination. Parcourez les résultats avec page et per_page. Utilisez la recherche par similarité pour trouver les meilleures correspondances, pas pour énumérer chacune d’entre elles.

AND ou OR — la seule décision à prendre par filtre

Les filtres à valeurs multiples (technologies, verticals, keywords, categories, …) acceptent un tableau. L’opérateur détermine ce que signifie « correspondance » :

OR (par défaut)
AND

Correspond à au moins une valeur. Renvoie les lignes dont le tableau chevauche l’entrée.

{
  "technologies": ["Python", "PostgreSQL", "Kubernetes"],
  "is_enable_similarity_search": true
}

Une entreprise est incluse si sa stack technologique contient au moins une des technologies Python, PostgreSQL ou Kubernetes.À utiliser quand : vous voulez une large couverture — « intéressé par n’importe lequel de ces éléments », « situé dans n’importe lequel de ces pays ».

Correspond à toutes les valeurs. Renvoie les lignes dont le tableau contient chaque valeur d’entrée.

{
  "technologies": [10191, 121],
  "filter_conditions": [
    { "key": "technologies", "operator": "and" }
  ]
}

Les identifiants numériques de tags proviennent de POST /technologies avec un keyword (et des endpoints équivalents pour les verticales et les catégories). Avec des noms en texte libre et AND, une entreprise doit correspondre à chacun des noms que vous avez listés.Une entreprise est incluse uniquement si sa stack technologique contient la totalité de [10191, 121] (Salesforce et HubSpot).À utiliser quand : vous voulez de la précision — « utilise l’ensemble de ces technologies ensemble », « taguée avec toutes ces verticales ».

Les filtres non listés dans filter_conditions utilisent l’opérateur par défaut (OR au sein d’un tableau, AND entre clés de filtre distinctes). Vous ne déclarez que les remplacements — jamais les valeurs par défaut.

Ce que vous pouvez remplacer

Chaque endpoint accepte des remplacements pour un ensemble de clés différent. Les clés proviennent de l’énumération OpenAPI de chaque schéma *_filter_conditions :

Endpoint entreprise

Clés company_filter_conditions : keywords, verticals, vertical_categories, vertical_sub_categories, technologies, categories, social_media, advertisement_target_locations, job_exclude_locations.

Endpoint personnes

Clés people_filter_conditions : keywords, verticals, vertical_categories, vertical_sub_categories, technologies, categories, social_media.

Endpoint annonces

Clés ads_filter_conditions : target_locations, publisher_platforms.

Les filtres de localisation et de lieu correspondent toujours à n’importe quelle valeur listée, sur tous les endpoints. filter_conditions ne les modifie pas.

Conseils de performance

Commencez par les filtres les plus restrictifs

Les lieux, les tranches d’effectifs et founded_dates réduisent l’ensemble de candidats plus rapidement que les filtres en texte libre ou par verticale. Combinez-les avec un ou deux filtres précis avant de recourir à la recherche par similarité.

N'abusez pas de AND sur de grands tableaux

AND exige que chaque valeur soit présente. Un AND sur 10 technologies renvoie un nombre de lignes proche de zéro. Privilégiez 2 à 4 valeurs par filtre AND ; passez à OR pour les requêtes exploratoires.

Utilisez is_enable_similarity_search pour une saisie en texte libre

Si vous ne pouvez pas fournir d’identifiants slug (verticales, technologies, catégories) et disposez uniquement de chaînes en texte libre, définissez is_enable_similarity_search: true et similarity_score: 0.7. Le moteur résout les correspondances avant d’appliquer le filtre — bien moins coûteux qu’un scan de texte.

Préférez les plages aux listes d'énumérations pour la taille et le chiffre d'affaires

employees: [[201, 500], [501, 1000]] (un tableau de tranches) et revenues: [1000000, 5000000] (une seule plage min/max) sont plus rapides et plus idiomatiques que de longues listes d’identifiants.

Filtres d’activité publicitaire

/companies/search peut filtrer sur l’empreinte publicitaire d’une entreprise — combien d’annonces elle diffuse, si certaines sont actuellement actives, quelles plateformes et formats elle utilise, et comment elle se classe par rapport aux autres annonceurs dans un pays donné. POST /companies/advertisements/search accepte également chacun de ces filtres (advertisement_active_ads, advertisement_running_ads, advertisement_total_ads, advertisement_platform_count, advertisement_format_count, advertisement_impressions_estimate, advertisement_formats, advertisement_country_activity) — une annonce est incluse si l’entreprise qui la possède satisfait la borne.

Filtre	Structure	Portée
`advertisement_active_ads`, `advertisement_running_ads`, `advertisement_total_ads`	plage `[min, max]`	Tous pays
`advertisement_platform_count`, `advertisement_format_count`	plage `[min, max]`	Tous pays
`advertisement_impressions_estimate`	plage `[min, max]`	Tous pays
`advertisement_formats`	tableau — `image`, `video`, `text`, `carousel`, `dynamic_product`, `document`, `message`, `event`, `article`, `spotlight`, `follow`, `job`, `engagement`	Tous pays
`advertisement_platforms`	tableau — `linkedin`, `facebook`, `google`, `tiktok`, `apple` (`meta` accepté comme alias de `facebook`)	Tous pays
`advertisement_publisher_platforms`, `advertisement_exclude_publisher_platforms`	tableau — `facebook`, `instagram`, `messenger`, `threads`, `audience_network`	Tous pays
`advertisement_status`	tableau — `currently_running` (a des annonces enregistrées), `active_last_30_min` (enregistrements d’annonces modifiés au cours des 30 dernières minutes)	Tous pays
`advertisement_country_activity`	objet, voir ci-dessous	Un pays

Utilisez null pour une borne ouverte — [1, null] signifie « au moins 1 », [null, 500] signifie « 500 ou moins ».

{
  "advertisement_active_ads": [1, null],
  "advertisement_formats": ["video"]
}

Classement au sein d’un pays

advertisement_country_activity limite le rang, le percentile et le score de volume à un seul pays à la fois — le rang publicitaire d’une entreprise aux États-Unis ne dit rien de son rang en Allemagne, donc country est obligatoire :

{
  "advertisement_country_activity": {
    "country": "US",
    "rank": [null, 500]
  }
}

rank décompte à partir du plus gros annonceur, comme dans une course. 1 est le plus gros annonceur de ce pays, et le chiffre augmente à mesure que le volume publicitaire diminue. Pour trouver les plus gros annonceurs, filtrez rank avec une borne supérieure basse — [null, 500] correspond au top 500. Filtrer [500, null] trouve tous ceux qui sont hors du top 499, ce qui est l’inverse de « gros annonceur ». Si vous voulez une version indépendante de l’échelle qui fonctionne de la même façon quel que soit le nombre d’annonceurs dans ce pays, utilisez plutôt percentile — il fonctionne dans l’autre sens, donc un chiffre plus élevé signifie un annonceur plus important : [90, null] correspond au top 10 %.

Combinez advertisement_country_activity avec les filtres tous-pays ci-dessus dans la même requête — par exemple, « classée dans le top 500 aux États-Unis, et ayant au moins 100 annonces actives à l’échelle de l’entreprise » :

{
  "advertisement_country_activity": { "country": "US", "rank": [null, 500] },
  "advertisement_active_ads": [100, null]
}

Classement des résultats

Filtrer sur advertisement_country_activity restreint quelles entreprises sont renvoyées ; cela ne suffit pas à en déterminer l’ordre. Pour obtenir d’abord les plus gros annonceurs de ce marché, demandez sort_by: "advertisement_country_rank" :

{
  "advertisement_country_activity": { "country": "HK", "rank": [1, 10] },
  "sort_by": "advertisement_country_rank"
}

Dès que advertisement_country_activity est présent, chaque entreprise porte également son classement dans ce pays, ce qui vous permet d’afficher le rang sur lequel vous avez filtré :

Champ	Signification
`advertisement_country_rank`	Position dans ce pays, 1 = plus gros annonceur. Les ex æquo partagent un rang, les nombres peuvent donc se répéter puis sauter.
`advertisement_country_percentile`	Part des annonceurs de ce pays que cette entreprise devance.
`advertisement_country_active_ads`	Annonces actives attribuées à ce pays — et non le `advertisement_active_ads` à l’échelle de l’entreprise.

sort_by: "advertisement_country_rank" est ignoré lorsque advertisement_country_activity est absent, car un rang n’existe qu’au sein d’un pays. Passez is_ascending_order: false pour lister d’abord les plus petits annonceurs du marché.

Repérer les nouveaux entrants sur un marché

advertisement_country_activity accepte également deux fenêtres de dates, ce qui vous permet de demander qui a commencé à faire de la publicité sur un marché plutôt que qui y est déjà important :

Clé	Signification
`first_seen`	`[from, to]` — quand la première publicité de l’entreprise dans ce pays a été diffusée. C’est le filtre « vient d’entrer sur ce marché ».
`last_seen`	`[from, to]` — quand sa publicité la plus récente dans ce pays a été diffusée. Utile pour la question inverse : qui s’est tu.

Entreprises entrées au Japon depuis le début du mois de juillet :

{
  "advertisement_country_activity": { "country": "JP", "first_seen": ["2026-07-01", null] }
}

Chaque borne peut être null pour une fenêtre ouverte d’un côté. Les dates sont interprétées dans le fuseau horaire de la requête. Une entreprise dont les publicités n’ont pas de date de début n’a pas de valeur de première détection et est considérée comme inconnue — elle n’est jamais signalée comme nouvelle. Combinez-la avec les clés de classement du même objet pour affiner davantage, par exemple les nouveaux entrants qui dépensent déjà beaucoup.

Étapes suivantes

filter_conditions

Page de référence — chaque clé prise en charge, chaque valeur par défaut, et des exemples AND/OR prêts à copier.

Filtres personnes + entreprise

Utilisez n’importe quel filtre entreprise à l’intérieur de /people/search. La fonctionnalité phare du moteur unifié.

Référence Recherche entreprise

Schéma complet de requête/réponse pour /companies/search.

Référence Recherche personnes

Schéma complet de requête/réponse pour /people/search.

Vous cherchez le guide de filtrage côté tableau de bord ? Voir Filtrer et exporter des contacts dans la base de connaissances.

Monitor

Recherche

Filtres

Personnes

Expansion

Pourquoi un moteur de filtres unifié ?

Un seul schéma, trois endpoints

AND/OR par filtre

Filtré avant la pagination

Mêmes filtres dans les Monitors

Anatomie d’une requête de recherche

`company_filters` : regrouper les clés au niveau entreprise

Même structure sur les variantes `/search/similar`

AND ou OR — la seule décision à prendre par filtre

Ce que vous pouvez remplacer

Endpoint entreprise

Endpoint personnes

Endpoint annonces

Conseils de performance

Filtres d’activité publicitaire

Classement au sein d’un pays

Classement des résultats

Repérer les nouveaux entrants sur un marché

Étapes suivantes

filter_conditions

Filtres personnes + entreprise

Référence Recherche entreprise

Référence Recherche personnes

​Pourquoi un moteur de filtres unifié ?

Un seul schéma, trois endpoints

AND/OR par filtre

Filtré avant la pagination

Mêmes filtres dans les Monitors

​Anatomie d’une requête de recherche

​company_filters : regrouper les clés au niveau entreprise

​Même structure sur les variantes /search/similar

​AND ou OR — la seule décision à prendre par filtre

​Ce que vous pouvez remplacer

Endpoint entreprise

Endpoint personnes

Endpoint annonces

​Conseils de performance

​Filtres d’activité publicitaire

​Classement au sein d’un pays

​Classement des résultats

​Repérer les nouveaux entrants sur un marché

​Étapes suivantes

filter_conditions

Filtres personnes + entreprise

Référence Recherche entreprise

Référence Recherche personnes

Pourquoi un moteur de filtres unifié ?

Anatomie d’une requête de recherche

`company_filters` : regrouper les clés au niveau entreprise

Même structure sur les variantes `/search/similar`

AND ou OR — la seule décision à prendre par filtre

Ce que vous pouvez remplacer

Conseils de performance

Filtres d’activité publicitaire

Classement au sein d’un pays

Classement des résultats

Repérer les nouveaux entrants sur un marché

Étapes suivantes