Filtros de Pessoas + Empresa

POST /people/search aceita todos os filtros de empresa que POST /companies/search aceita. Você não precisa mais pré-buscar empresas, coletar seus IDs e alimentá-los em uma segunda consulta de pessoas — uma única requisição faz as duas camadas.

Duas famílias de parâmetros, um único corpo

O corpo de uma requisição /people/search é dividido conceitualmente em duas famílias de filtros. Elas ficam no mesmo nível no JSON, e você pode misturá-las livremente.

Nível de pessoa
Nível de empresa

Filtra pelos atributos da pessoa:

Parâmetro	Descrição
`people_titles`	Cargos (texto livre ou slug)
`management_levels`	`founder`, `c_suite`, `vp`, `director`, `manager`, …
`departments`	`master_engineering`, `master_sales`, …
`department_functions`	Slugs de subdepartamento / função
`people_locations`	Códigos de país da localização da pessoa
`people_groups`	IDs de grupos salvos
`peoples`	Valores específicos de `people_search_id`
`linkedin_urls`	URLs do LinkedIn da pessoa
`social_media`	Identificadores de redes sociais por rede

Filtra pelos atributos da empresa onde a pessoa trabalha — mesmos nomes de /companies/search, com um pequeno conjunto de chaves de localização com prefixo company_:

Parâmetro	Descrição
`technologies`	IDs de slug de tecnologias que a empresa usa
`categories`	IDs de slug de categoria
`verticals`	IDs de slug de vertical
`vertical_categories`	IDs de slug de categoria vertical
`vertical_sub_categories`	IDs de slug de subcategoria vertical
`keywords`	Palavras-chave em texto livre comparadas com a descrição da empresa
`founded_dates`	Faixa de ano de fundação, por exemplo `[2015, 2023]`
`employees`	Faixas de funcionários, por exemplo `[[100, 500], [501, 1000]]`
`revenues`	Faixas de receita em USD
`company_locations`	Códigos de país da sede da empresa
`company_exclude_locations`	Códigos de país a excluir
`company_places`	Nomes de cidade / região a incluir
`company_exclude_places`	Nomes de cidade / região a excluir
`companies`	Valores específicos de `domain_search_id`
`domains`	Domínios específicos de empresa
`company_linkedin_urls`	URLs do LinkedIn da empresa

O prefixo company_ existe apenas nos filtros de localização/lugar porque os nomes puros places / locations já são usados para o endereço da pessoa. Todo o restante usa o nome puro da empresa (technologies, e não company_technologies).

Monte uma consulta em quatro etapas

Defina o predicado de pessoa

Quem, exatamente? Cargo, senioridade, departamento, país. Mantenha essa camada no nível superior do corpo — o predicado de empresa geralmente é responsável pela precisão.

Defina o predicado de empresa

Em quais empresas essas pessoas precisam trabalhar? Setor, porte, ano de fundação, país da sede, pilha de tecnologia. Agrupe essas chaves sob um objeto company_filters: {...} para deixar claro a qual camada cada chave pertence.

Escolha AND/OR por filtro via filter_conditions

Para qualquer filtro multivalorado que precise de precisão (por exemplo, “usa todas estas tecnologias”), adicione uma entrada a filter_conditions dentro de company_filters. O padrão é OR.

Envie a requisição

POST /people/search. Ambos os estilos são aceitos, mas company_filters: {...} fica mais legível e corresponde ao formato de payload dos Monitores.

Exemplo completo

A consulta: VPs de Engenharia ou CTOs em empresas de médio porte baseadas nos EUA, fundadas entre 2015 e 2023, com 100 a 5.000 funcionários, que usam tanto Kubernetes quanto Docker, mas excluindo empresas com sede em São Francisco.

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": {
      "company_locations": ["US"],
      "company_exclude_places": ["San Francisco"],
      "founded_dates": [2010, 2024],
      "employees": [[100, 500], [501, 1000], [1001, 5000]],
      "technologies": ["Kubernetes", "Docker"],
      "is_enable_similarity_search": true
    },

    "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": {
            "company_locations": ["US"],
            "company_exclude_places": ["San Francisco"],
            "founded_dates": [2010, 2024],
            "employees": [[100, 500], [501, 1000], [1001, 5000]],
            "technologies": ["Kubernetes", "Docker"],
            "is_enable_similarity_search": True,
        },

        "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: {
      company_locations: ["US"],
      company_exclude_places: ["San Francisco"],
      founded_dates: [2010, 2024],
      employees: [[100, 500], [501, 1000], [1001, 5000]],
      technologies: ["Kubernetes", "Docker"],
      is_enable_similarity_search: true,
    },

    per_page: 25,
    page: 1,
  }),
});
console.log(await response.json());

Referência de remapeamento de chaves

Quando /people/search repassa filtros de empresa para o mecanismo compartilhado, as chaves de localização/lugar são renomeadas para suas formas puras. Os nomes puros são o que o mecanismo — e filter_conditions[].key — realmente enxergam:

Você envia (nome da API de pessoas)	O mecanismo vê (nome da API de empresa)
`company_locations`	`locations`
`company_exclude_locations`	`exclude_locations`
`company_places`	`places`
`company_exclude_places`	`exclude_places`
`technologies`, `verticals`, `vertical_categories`, `vertical_sub_categories`, `categories`, `keywords`, `founded_dates`, `employees`, `revenues`	passam sem alteração

É por isso que filter_conditions[].key para localizações em nível de empresa usa os nomes puros:

{
  "company_places": ["New York", "Boston"],
  "filter_conditions": [
    { "key": "places", "operator": "and" }
  ]
}

{ "key": "company_places", "operator": "and" } é ignorado silenciosamente — o mecanismo não reconhece o nome com prefixo. Sempre referencie o nome do mecanismo em filter_conditions.

Junções (joins) por trás dos panos

Adicionar qualquer filtro em nível de empresa muda a junção de pessoas para empresas de LEFT JOIN para INNER JOIN. Pessoas sem uma empresa reconhecida em registro são excluídas do resultado, mesmo quando correspondem a todos os filtros em nível de pessoa.

Se a sua busca cair para zero linhas no momento em que você adiciona company_locations ou technologies, verifique se o seu conjunto de dados tem empresas vinculadas às pessoas que você espera. O mecanismo prioriza a correção em vez do recall aqui — ele nunca inventa empresas para satisfazer o filtro.

Você verá esse mesmo comportamento de junção refletido na resposta: toda pessoa retornada inclui um objeto company preenchido sempre que algum filtro de empresa foi aplicado.

Padrões comuns

Account-Based Marketing (ABM)

Segmente uma lista fixa de empresas (companies ou domains) e, em seguida, adicione filtros em nível de pessoa para encontrar os compradores certos dentro de cada uma.

{
  "people_titles": ["VP Marketing", "CMO"],
  "management_levels": ["vp", "c_suite"],
  "company_filters": {
    "companies": ["67c4696b-…", "f1e2d3c4-…", "0a9b8c7d-…"]
  }
}

Descoberta de Perfil de Cliente Ideal (ICP)

Descreva o formato da empresa, não contas específicas. Use faixas e verticais — o mecanismo retorna as pessoas que se encaixam.

{
  "people_titles": ["Head of Engineering"],
  "company_filters": {
    "verticals": [12, 47],
    "company_locations": ["US", "CA"],
    "founded_dates": [2015, 2023],
    "employees": [[51, 200], [201, 500]],
    "filter_conditions": [
      { "key": "verticals", "operator": "and" }
    ]
  }
}

Prospecção orientada por tecnologia

Encontre compradores em empresas que rodam uma pilha específica. AND em technologies é a substituição típica.

{
  "people_titles": ["RevOps", "Sales Operations"],
  "departments": ["master_sales"],
  "company_filters": {
    "technologies": [114, 287, 452],
    "filter_conditions": [
      { "key": "technologies", "operator": "and" }
    ]
  }
}

Deslocamento de concorrente

Encontre tomadores de decisão em empresas que usam o produto de um concorrente (uma tecnologia), mas não o seu (excluído via categories ou uma passagem de filtro separada).

{
  "people_titles": ["VP Sales"],
  "management_levels": ["vp"],
  "company_filters": {
    "technologies": [287]
  }
}

Depois execute novamente com technologies: [114] (o ID de tag do seu produto) e compare os resultados no seu lado.

Próximos passos

filter_conditions

Referência completa — cada chave, cada padrão, receitas AND/OR copiáveis.

Visão Geral de Filtros

O modelo mental por trás do mecanismo de filtro unificado.

Referência de People Search

Esquema completo de requisição/resposta para /people/search.

Referência de Company Search

Esquema completo de requisição/resposta para /companies/search.

Monitoramento

Busca

Filtros

Pessoas

Expansão

Duas famílias de parâmetros, um único corpo

Monte uma consulta em quatro etapas

Exemplo completo

Referência de remapeamento de chaves

Junções (joins) por trás dos panos

Padrões comuns

Próximos passos

filter_conditions

Visão Geral de Filtros

Referência de People Search

Referência de Company Search

​Duas famílias de parâmetros, um único corpo

​Monte uma consulta em quatro etapas

​Exemplo completo

​Referência de remapeamento de chaves

​Junções (joins) por trás dos panos

​Padrões comuns

​Próximos passos

filter_conditions

Visão Geral de Filtros

Referência de People Search

Referência de Company Search

Duas famílias de parâmetros, um único corpo

Monte uma consulta em quatro etapas

Exemplo completo

Referência de remapeamento de chaves

Junções (joins) por trás dos panos

Padrões comuns

Próximos passos