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_technical`, `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

No nível superior de /people/search, os filtros de localização e de lugar da empresa levam o prefixo company_; as chaves puras locations / places não são aceitas ali e são reportadas em metadata.ignored_fields. Todo o restante usa o nome puro da empresa (technologies, e não company_technologies). Dentro de company_filters, qualquer uma das duas grafias funciona.

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

Em /people/search, as chaves de localização e de lugar da empresa levam o prefixo company_. Elas correspondem aos nomes da Company Search da seguinte forma:

Você envia em `/people/search`	Nome na Company Search
`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`	mesmo nome

As chaves de filter_conditions nunca levam o prefixo — use technologies, verticals, keywords e os demais nomes listados em Chaves suportadas. Os filtros de localização e de lugar sempre correspondem a qualquer valor listado.

Pessoas sem empresa

Adicionar qualquer filtro em nível de empresa limita o resultado a pessoas com uma empresa reconhecida em registro. Pessoas sem uma são excluídas, 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 as pessoas que você espera têm uma empresa vinculada.

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": [69086912],
    "company_locations": ["US", "CA"],
    "founded_dates": [2015, 2023],
    "employees": [[51, 200], [201, 500]]
  }
}

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": [10191, 121],
    "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

Pessoas sem empresa

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

​Pessoas sem empresa

​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

Pessoas sem empresa

Padrões comuns

Próximos passos