Filter-Übersicht - Pubrio Documentation

Die Such-Endpunkte von Pubrio (/companies/search, /people/search, /companies/advertisements/search) teilen sich eine einzige Filter-Engine. Sie stellen einen Anfrage-Body einmal zusammen, und dieselben Regeln gelten über alle Endpunkte hinweg — einschließlich der Art, wie Mehrwert-Filter kombiniert werden, wie Standorte abgeglichen werden und wie Sie den Standardoperator mit filter_conditions überschreiben.

Warum eine einheitliche Filter-Engine?

Ein Schema, drei Endpunkte

Filter auf Unternehmensebene wie technologies, verticals und founded_dates funktionieren identisch auf /companies/search, /people/search und innerhalb von Monitor-company_filters — Sie lernen sie einmal.

AND/OR pro Filter

Der Standard ist OR (beliebiger Treffer). Heben Sie einzelne Filter auf AND (jeder muss zutreffen) an, indem Sie einen Eintrag zu filter_conditions hinzufügen — ohne den Rest des Bodys zu ändern.

Gefiltert, bevor Sie blättern

Jeder Filter wird angewendet, bevor Ergebnisse zurückgegeben werden, sodass jede Seite und jede Gesamtzahl Ihre gesamte Anfrage widerspiegelt. Keine anwendungsseitige Nachfilterung.

Dieselben Filter in Monitoren

Der company_filters-Block in Monitoren akzeptiert dieselbe Form, sodass ein funktionierender Such-Payload auch ein funktionierender Monitor-Payload ist.

Aufbau einer Suchanfrage

Jede Suchanfrage besteht aus drei Ebenen im selben JSON-Body:

Ebene	Wo sie liegt	Beispiele
Personenfilter	Schlüssel auf oberster Ebene	`people_titles`, `management_levels`, `departments`, `people_locations`
Unternehmensfilter	verschachtelt unter `company_filters: {...}` (empfohlen) — auch auf oberster Ebene akzeptiert	`technologies`, `verticals`, `founded_dates`, `employees`, `company_locations`
Operator-Überschreibungen	`filter_conditions`-Array (innerhalb von `company_filters`, wenn Unternehmensschlüssel überschrieben werden)	`[{ "key": "technologies", "operator": "and" }]`

Eine minimale /people/search-Anfrage, die alle drei Ebenen nutzt:

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`: Unternehmensschlüssel gruppiert halten

Das Wrapper-Objekt company_filters: {...} ist die empfohlene Art, Filter auf Unternehmensebene zu senden — es trennt visuell, welche Schlüssel die Person filtern und welche das Unternehmen, und entspricht der Form, die Monitore bereits verwenden, sodass Payloads sauber zwischen Such- und Monitor-Konfigurationen übertragbar sind. Beide Stile funktionieren; die Engine flacht die eingebettete Form vor der Verarbeitung auf die oberste Ebene ab, und Schlüssel auf oberster Ebene gewinnen bei Konflikten:

{
  "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"]
}

Wenn Sie eine filter_conditions-Überschreibung für einen Unternehmensschlüssel hinzufügen, platzieren Sie diese innerhalb von company_filters, damit sie mit den überschriebenen Schlüsseln zusammenbleibt.

Dieselbe Form bei den `/search/similar`-Varianten

POST /companies/search/similar und POST /people/search/similar akzeptieren denselben Filter-Body wie ihre nicht-ähnlichen Gegenstücke (einschließlich des company_filters-Wrappers und filter_conditions). Jeder fügt zusätzlich einen Ähnlichkeitsschritt hinzu:

	Was sie zusätzlich benötigen	Was Sie zusätzlich erhalten
`/companies/search/similar`	Ein Referenzunternehmen — `domain_search_id`, `domain` oder `linkedin_url`	Jedes Ergebnis erhält einen `similarity_score` (Fließkommazahl, 0–1)
`/people/search/similar`	Eine Referenzperson/-titel — eines von `people_titles`, `people_search_id`, `linkedin_url`, `linkedin_urls` oder `peoples`	Die Personen, die Ihrer Referenz am ähnlichsten sind — Jedes Ergebnis erhält einen `similarity_score` (Fließkommazahl, 0–1)

Filter grenzen den Kandidatenpool ein, bevor die Ähnlichkeit angewendet wird — die Kombination von company_locations: ["US"] mit /people/search/similar liefert also die ähnlichsten US-basierten Personen zu Ihren Referenztiteln, das Muster „finde mehr Personen wie X innerhalb dieser Einschränkungen”.

/companies/search/similar gibt data als einfaches Array von Unternehmen zurück — es gibt kein pagination-Objekt. Blättern Sie mit page und per_page durch die Ergebnisse. Verwenden Sie die Ähnlichkeitssuche, um die besten Treffer zu finden, nicht um jeden einzelnen aufzuzählen.

AND vs. OR — die eine Entscheidung pro Filter

Mehrwert-Filter (technologies, verticals, keywords, categories, …) akzeptieren ein Array. Der Operator entscheidet, was „Treffer” bedeutet:

OR (Standard)
AND

Beliebiger Treffer. Liefert Zeilen, deren Array sich mit der Eingabe überschneidet.

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

Ein Unternehmen wird einbezogen, wenn sein Tech-Stack mindestens eines von Python, PostgreSQL oder Kubernetes enthält.Verwenden, wenn: Sie breite Reichweite möchten — „interessiert an einem beliebigen dieser”, „in einem beliebigen dieser Länder ansässig”.

Jeder Wert muss zutreffen. Liefert Zeilen, deren Array jeden Eingabewert enthält.

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

Numerische Tag-IDs stammen von POST /technologies mit einem keyword (und den entsprechenden Endpunkten für Verticals und Kategorien). Bei Freitextnamen und AND muss ein Unternehmen auf jeden von Ihnen aufgeführten Namen zutreffen.Ein Unternehmen wird nur einbezogen, wenn sein Tech-Stack alle von [10191, 121] (Salesforce und HubSpot) enthält.Verwenden, wenn: Sie Präzision möchten — „nutzt alle dieser Technologien zusammen”, „mit allen dieser Verticals getaggt”.

Nicht in filter_conditions aufgeführte Filter verwenden den Standardoperator (OR innerhalb eines Arrays, AND über unterschiedliche Filterschlüssel hinweg). Sie deklarieren nur die Überschreibungen — nie die Standardwerte.

Was Sie überschreiben können

Jeder Endpunkt akzeptiert Überschreibungen für eine andere Schlüsselmenge. Die Schlüssel stammen aus dem OpenAPI-Enum jedes *_filter_conditions-Schemas:

Unternehmens-Endpunkt

company_filter_conditions-Schlüssel: keywords, verticals, vertical_categories, vertical_sub_categories, technologies, categories, social_media, advertisement_target_locations, job_exclude_locations.

Personen-Endpunkt

people_filter_conditions-Schlüssel: keywords, verticals, vertical_categories, vertical_sub_categories, technologies, categories, social_media.

Anzeigen-Endpunkt

ads_filter_conditions-Schlüssel: target_locations, publisher_platforms.

Standort- und Ortsfilter treffen immer auf jeden beliebigen aufgeführten Wert zu, bei jedem Endpunkt. filter_conditions ändert daran nichts.

Performance-Tipps

Mit den engsten Filtern beginnen

Standorte, Mitarbeiter-Bucketwerte und founded_dates reduzieren die Kandidatenmenge schneller als Freitext- oder Vertical-Filter. Kombinieren Sie sie mit ein oder zwei präzisen Filtern, bevor Sie zur Ähnlichkeitssuche greifen.

Große Arrays nicht übermäßig mit AND verknüpfen

AND verlangt, dass jeder Wert vorhanden ist. Ein AND mit 10 Technologien liefert fast null Zeilen. Bevorzugen Sie 2–4 Werte pro AND-Filter; wechseln Sie zu OR für explorative Abfragen.

is_enable_similarity_search für Freitext-Eingaben verwenden

Wenn Sie keine Slug-IDs (Verticals, Technologien, Kategorien) angeben können und nur Freitext-Strings haben, setzen Sie is_enable_similarity_search: true und similarity_score: 0.7. Die Engine löst Treffer auf, bevor der Filter angewendet wird — deutlich günstiger als das Durchsuchen von Text.

Bereiche statt Enum-Listen für Größe und Umsatz bevorzugen

employees: [[201, 500], [501, 1000]] (ein Array von Buckets) und revenues: [1000000, 5000000] (ein einzelner Min-/Max-Bereich) sind schneller und idiomatischer als lange ID-Listen.

Filter für Werbeaktivität

/companies/search kann nach dem Werbeprofil eines Unternehmens filtern — wie viele Anzeigen es schaltet, ob welche aktuell aktiv sind, welche Plattformen und Formate es nutzt und wie es im Vergleich zu anderen Werbetreibenden in einem bestimmten Land rangiert. POST /companies/advertisements/search akzeptiert jeden dieser Filter ebenfalls (advertisement_active_ads, advertisement_running_ads, advertisement_total_ads, advertisement_platform_count, advertisement_format_count, advertisement_impressions_estimate, advertisement_formats, advertisement_country_activity) — eine Anzeige wird einbezogen, wenn das zugehörige Unternehmen die Bedingung erfüllt.

Filter	Form	Geltungsbereich
`advertisement_active_ads`, `advertisement_running_ads`, `advertisement_total_ads`	`[min, max]`-Bereich	Alle Länder
`advertisement_platform_count`, `advertisement_format_count`	`[min, max]`-Bereich	Alle Länder
`advertisement_impressions_estimate`	`[min, max]`-Bereich	Alle Länder
`advertisement_formats`	Array — `image`, `video`, `text`, `carousel`, `dynamic_product`, `document`, `message`, `event`, `article`, `spotlight`, `follow`, `job`, `engagement`	Alle Länder
`advertisement_platforms`	Array — `linkedin`, `facebook`, `google`, `tiktok`, `apple` (`meta` als Alias für `facebook` akzeptiert)	Alle Länder
`advertisement_publisher_platforms`, `advertisement_exclude_publisher_platforms`	Array — `facebook`, `instagram`, `messenger`, `threads`, `audience_network`	Alle Länder
`advertisement_status`	Array — `currently_running` (hat erfasste Anzeigen), `active_last_30_min` (Anzeigendatensätze haben sich in den letzten 30 Minuten geändert)	Alle Länder
`advertisement_country_activity`	Objekt, siehe unten	Ein Land

Verwenden Sie null für eine offene Grenze — [1, null] bedeutet „mindestens 1”, [null, 500] bedeutet „500 oder weniger”.

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

Rangfolge innerhalb eines Landes

advertisement_country_activity bezieht Rang, Perzentil und Volumen-Score jeweils auf ein Land — der Anzeigenrang eines Unternehmens in den USA sagt nichts über seinen Rang in Deutschland aus, daher ist country erforderlich:

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

rank zählt vom größten Werbetreibenden abwärts, wie bei einem Rennen. 1 ist der größte Werbetreibende in diesem Land, und die Zahl steigt, während das Werbevolumen sinkt. Um die größten Werbetreibenden zu finden, filtern Sie rank mit einer niedrigen Obergrenze — [null, 500] sind die Top 500. Ein Filter von [500, null] findet alle außerhalb der Top 499, das Gegenteil von „großer Werbetreibender”. Wenn Sie eine skalenunabhängige Version möchten, die unabhängig von der Anzahl der Werbetreibenden in diesem Land gleich funktioniert, verwenden Sie stattdessen percentile — sie läuft in die andere Richtung, sodass eine höhere Zahl einen größeren Werbetreibenden bedeutet: [90, null] sind die Top 10 %.

Kombinieren Sie advertisement_country_activity mit den obigen länderübergreifenden Filtern in derselben Anfrage — zum Beispiel „unter den Top 500 in den USA rangiert und unternehmensweit mindestens 100 aktive Anzeigen”:

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

Rangfolge der Ergebnisse

Ein Filter auf advertisement_country_activity grenzt ein, welche Unternehmen zurückkommen; über die Reihenfolge entscheidet er für sich genommen nicht. Um die größten Werbetreibenden dieses Marktes zuerst zu erhalten, fordern Sie sort_by: "advertisement_country_rank" an:

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

Sobald advertisement_country_activity gesetzt ist, führt jedes Unternehmen zusätzlich seine Position in diesem Land mit, sodass Sie den Rang anzeigen können, nach dem Sie gefiltert haben:

Feld	Bedeutung
`advertisement_country_rank`	Position in diesem Land, 1 = größter Werbetreibender. Bei Gleichstand teilen sich mehrere Unternehmen einen Rang, daher können sich Zahlen wiederholen und anschließend Sprünge entstehen.
`advertisement_country_percentile`	Anteil der Werbetreibenden in diesem Land, die dieses Unternehmen hinter sich lässt.
`advertisement_country_active_ads`	Aktive Anzeigen, die diesem Land zugerechnet werden — nicht das unternehmensweite `advertisement_active_ads`.

sort_by: "advertisement_country_rank" wird ignoriert, wenn advertisement_country_activity fehlt, denn einen Rang gibt es nur innerhalb eines Landes. Übergeben Sie is_ascending_order: false, um die kleinsten Werbetreibenden des Marktes zuerst aufzulisten.

Neue Marktteilnehmer finden

advertisement_country_activity akzeptiert außerdem zwei Zeitfenster, sodass Sie fragen können, wer in einem Markt mit Werbung begonnen hat, statt wer dort bereits groß ist:

Schlüssel	Bedeutung
`first_seen`	`[from, to]` — wann die früheste Anzeige des Unternehmens in diesem Land lief. Das ist der Filter „neu in diesem Markt”.
`last_seen`	`[from, to]` — wann seine jüngste Anzeige in diesem Land lief. Nützlich für die umgekehrte Frage: Wer ist still geworden.

Unternehmen, die seit Anfang Juli in Japan eingestiegen sind:

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

Jede Grenze darf null sein, um das Fenster nach einer Seite offen zu lassen. Datumsangaben werden in der Zeitzone der Anfrage interpretiert. Ein Unternehmen, dessen Anzeigen kein Startdatum tragen, hat keinen Erstsichtungswert und gilt als unbekannt — es wird nie als neu gemeldet. Kombinieren Sie den Filter mit den Rangschlüsseln im selben Objekt, um weiter einzugrenzen, zum Beispiel neue Marktteilnehmer, die bereits viel in Werbung investieren.

Nächste Schritte

filter_conditions

Referenzseite — jeder unterstützte Schlüssel, jeder Standard und kopierbare AND-/OR-Rezepte.

People + Company Filters

Verwenden Sie jeden Unternehmensfilter innerhalb von /people/search. Die Hauptfunktion der einheitlichen Engine.

Company Search reference

Vollständiges Anfrage-/Antwortschema für /companies/search.

People Search reference

Vollständiges Anfrage-/Antwortschema für /people/search.

Suchen Sie die Anleitung zum dashboardseitigen Filtern? Siehe Filtering & Exporting Contacts in der Knowledge Base.

​Warum eine einheitliche Filter-Engine?

Ein Schema, drei Endpunkte

AND/OR pro Filter

Gefiltert, bevor Sie blättern

Dieselben Filter in Monitoren

​Aufbau einer Suchanfrage

​company_filters: Unternehmensschlüssel gruppiert halten

​Dieselbe Form bei den /search/similar-Varianten

​AND vs. OR — die eine Entscheidung pro Filter

​Was Sie überschreiben können

Unternehmens-Endpunkt

Personen-Endpunkt

Anzeigen-Endpunkt

​Performance-Tipps

​Filter für Werbeaktivität

​Rangfolge innerhalb eines Landes

​Rangfolge der Ergebnisse

​Neue Marktteilnehmer finden

​Nächste Schritte

filter_conditions

People + Company Filters

Company Search reference

People Search reference

Warum eine einheitliche Filter-Engine?

Aufbau einer Suchanfrage

`company_filters`: Unternehmensschlüssel gruppiert halten

Dieselbe Form bei den `/search/similar`-Varianten

AND vs. OR — die eine Entscheidung pro Filter

Was Sie überschreiben können

Performance-Tipps

Filter für Werbeaktivität

Rangfolge innerhalb eines Landes

Rangfolge der Ergebnisse

Neue Marktteilnehmer finden

Nächste Schritte