/companies/search, /people/search, /companies/advertisements/search) comparten un único motor de filtros. Compones el cuerpo de la solicitud una vez y las mismas reglas se aplican en todos los endpoints — incluida la forma en que se combinan los filtros multivalor, cómo se comparan las ubicaciones y cómo anulas el operador por defecto con filter_conditions.
¿Por qué un motor de filtros unificado?
Un esquema, tres endpoints
Los filtros a nivel de empresa como
technologies, verticals y founded_dates funcionan de forma idéntica en /companies/search, /people/search y dentro de company_filters de Monitor — los aprendes una sola vez.AND/OR por filtro
El valor por defecto es OR (coincide con cualquiera). Promueve filtros individuales a AND (coincide con todos) agregando una entrada a
filter_conditions — sin tocar el resto del cuerpo.Filtrado antes de paginar
Todos los filtros se aplican antes de devolver los resultados, por lo que cada página y cada total reflejan tu solicitud completa. Sin post-filtrado del lado de la aplicación.
Los mismos filtros en Monitores
El bloque
company_filters en Monitores acepta la misma forma, por lo que un payload de búsqueda que funciona también funciona como payload de monitor.Anatomía de una solicitud de búsqueda
Cada solicitud de búsqueda se construye a partir de tres capas en el mismo cuerpo JSON:
Una solicitud mínima a
/people/search que usa las tres capas:
company_filters: mantén agrupadas las claves de nivel de empresa
El objeto contenedor company_filters: {...} es la forma recomendada de enviar filtros a nivel de empresa — separa visualmente qué claves filtran a la persona de cuáles filtran a la empresa, y coincide con la forma que ya usan los Monitores, de modo que los payloads se transfieren limpiamente entre configuraciones de búsqueda y de monitor.
Ambos estilos funcionan; el motor aplana la forma envuelta al nivel superior antes de procesar, y las claves de nivel superior ganan en caso de conflicto:
filter_conditions para una clave de nivel de empresa, colócala dentro de company_filters para que viaje junto con las claves que anula.
Misma forma en las variantes /search/similar
POST /companies/search/similar y POST /people/search/similar aceptan el mismo cuerpo de filtros que sus contrapartes sin “similar” (incluyendo el contenedor company_filters y filter_conditions). Cada uno agrega un paso de similitud adicional:
Los filtros acotan el conjunto de candidatos antes de que se aplique la similitud — por lo que combinar
company_locations: ["US"] con /people/search/similar devuelve a las personas con sede en EE. UU. más cercanas a tus títulos de referencia, que es el patrón “encuentra más personas como X dentro de estas restricciones”.
/companies/search/similar devuelve data como un array simple de empresas — no hay un objeto pagination. Recorre los resultados con page y per_page. Usa la búsqueda por similitud para encontrar las mejores coincidencias, no para enumerar cada una de ellas.AND frente a OR — la única decisión que tomas por filtro
Los filtros multivalor (technologies, verticals, keywords, categories, …) aceptan un array. El operador decide qué significa “coincidencia”:
- OR (por defecto)
- AND
Coincide con cualquier valor. Devuelve filas cuyo array se solapa con la entrada.Una empresa se incluye si su stack tecnológico contiene al menos uno de
Python, PostgreSQL o Kubernetes.Úsalo cuando: quieres un alcance amplio — “interesado en cualquiera de estos”, “ubicado en cualquiera de estos países”.Los filtros no listados en
filter_conditions usan el operador por defecto (OR dentro de un array, AND entre claves de filtro distintas). Solo declaras las anulaciones — nunca los valores por defecto.Qué puedes anular
Cada endpoint acepta anulaciones para un conjunto de claves distinto. Las claves provienen del enum de OpenAPI en cada esquema*_filter_conditions:
Endpoint de empresas
Claves de
company_filter_conditions: keywords, verticals, vertical_categories, vertical_sub_categories, technologies, categories, social_media, advertisement_target_locations, job_exclude_locations.Endpoint de personas
Claves de
people_filter_conditions: keywords, verticals, vertical_categories, vertical_sub_categories, technologies, categories, social_media.Endpoint de anuncios
Claves de
ads_filter_conditions: target_locations, publisher_platforms.Consejos de rendimiento
Empieza por los filtros más restrictivos
Empieza por los filtros más restrictivos
Las ubicaciones, los rangos de empleados y
founded_dates reducen el conjunto de candidatos más rápido que los filtros de texto libre o de vertical. Combínalos con uno o dos filtros precisos antes de recurrir a la búsqueda por similitud.No abuses de AND en arrays grandes
No abuses de AND en arrays grandes
AND exige que cada valor esté presente. Un AND de 10 tecnologías devuelve casi cero filas. Prefiere entre 2 y 4 valores por filtro AND; cambia a OR para consultas exploratorias.
Usa is_enable_similarity_search para entradas de texto libre
Usa is_enable_similarity_search para entradas de texto libre
Si no puedes proporcionar IDs de slug (verticales, tecnologías, categorías) y solo tienes cadenas de texto libre, configura
is_enable_similarity_search: true y similarity_score: 0.7. El motor resuelve las coincidencias antes de aplicar el filtro — mucho más económico que escanear texto.Prefiere rangos sobre listas de enum para tamaño e ingresos
Prefiere rangos sobre listas de enum para tamaño e ingresos
employees: [[201, 500], [501, 1000]] (un array de rangos) y revenues: [1000000, 5000000] (un único rango mínimo/máximo) son más rápidos y más idiomáticos que listas largas de IDs.Filtros de actividad publicitaria
/companies/search puede filtrar por la huella publicitaria de una empresa — cuántos anuncios ejecuta, si alguno está actualmente activo, qué plataformas y formatos usa, y cómo se clasifica frente a otros anunciantes en un país determinado. POST /companies/advertisements/search también acepta todos estos filtros (advertisement_active_ads, advertisement_running_ads, advertisement_total_ads, advertisement_platform_count, advertisement_format_count, advertisement_impressions_estimate, advertisement_formats, advertisement_country_activity) — un anuncio se incluye si la empresa propietaria cumple el límite.
Usa
null para un límite abierto — [1, null] significa “al menos 1”, [null, 500] significa “500 o menos”.
Clasificación dentro de un país
advertisement_country_activity acota el rango, el percentil y la puntuación de volumen a un país a la vez — el rango publicitario de una empresa en EE. UU. no dice nada sobre su rango en Alemania, por lo que country es obligatorio:
advertisement_country_activity con los filtros de todos los países anteriores en la misma solicitud — por ejemplo, “clasificado en el top 500 en EE. UU., y tiene al menos 100 anuncios activos a nivel de empresa”:
Ordenación de los resultados
Filtrar poradvertisement_country_activity acota qué empresas se devuelven; por sí solo no decide el orden. Para obtener primero a los mayores anunciantes de ese mercado, pide sort_by: "advertisement_country_rank":
advertisement_country_activity esté presente, cada empresa lleva además su posición en ese país, de modo que puedes mostrar el rango por el que has filtrado:
sort_by: "advertisement_country_rank" se ignora cuando advertisement_country_activity no está presente, ya que un rango solo existe dentro de un país. Pasa is_ascending_order: false para listar primero a los anunciantes más pequeños del mercado.
Encontrar nuevos entrantes en un mercado
advertisement_country_activity también acepta dos ventanas de fechas, de modo que puedes preguntar quién empezó a anunciarse en un mercado en lugar de quién ya es grande allí:
Empresas que entraron en Japón desde principios de julio:
null para dejar la ventana abierta. Las fechas se interpretan en la zona horaria de la petición. Una empresa cuyos anuncios no llevan fecha de inicio no tiene valor de primera detección y se trata como desconocida — nunca se reporta como nueva. Combínalo con las claves de clasificación del mismo objeto para acotar más, por ejemplo nuevos entrantes que ya invierten mucho.
Próximos pasos
filter_conditions
Página de referencia — cada clave admitida, cada valor por defecto, y recetas AND/OR copiables.
Personas + Filtros de empresa
Usa cualquier filtro de empresa dentro de
/people/search. La función destacada del motor unificado.Referencia de Company Search
Esquema completo de solicitud/respuesta para
/companies/search.Referencia de People Search
Esquema completo de solicitud/respuesta para
/people/search.¿Buscas el recorrido de filtrado del lado del dashboard? Consulta Filtrar y exportar contactos en la Base de conocimiento.