Guia de Filtros da API - Consulta Social

Este documento descreve como filtrar perfis profissionais utilizando a API Social. Todos os filtros seguem o padrão de query com objeto $filter.

Estrutura Básica

{
  "$filter": {
    "$and": [{ "campo": "valor" }, { "outro_campo": "outro_valor" }]
  }
}

Você também pode usar $or para filtros alternativos:

{
  "$filter": {
    "$or": [{ "campo": "valor1" }, { "campo": "valor2" }]
  }
}

1. Identificação (4 campos)

1.1 Nome Completo

{
  "$filter": {
    "full_name": "Carlos Silva"
  }
}

1.2 Primeiro Nome

{
  "$filter": {
    "first_name": "Carlos"
  }
}

1.3 Sobrenome

{
  "$filter": {
    "last_name": "Silva"
  }
}

1.4 ID Público do Perfil

{
  "$filter": {
    "profile_public_id": "carlos-silva-123abc"
  }
}

Útil para buscar um perfil específico pelo identificador da URL do LinkedIn

2. Empresa Atual (3 campos)

2.1 Nome da Empresa

{
  "$filter": {
    "current_company": "AMBEV"
  }
}

2.2 ID da Empresa

{
  "$filter": {
    "current_company_id": 2345678
  }
}

Use o ID numérico para buscas exatas e estáveis

2.3 ID Público da Empresa

{
  "$filter": {
    "current_company_public_id": "ambev"
  }
}

3. Cargo e Área (3 campos)

3.1 Cargo Atual

{
  "$filter": {
    "current_job_title": { "$fuzzy": "Gerente de Projetos" }
  }
}

Use $fuzzy para variações de escrita (ex: "Gerente de Projeto", "Project Manager")

3.2 Senioridade

{
  "$filter": {
    "seniority": "COORDENADOR"
  }
}

Valores possíveis:

OUTROS

COORDENADOR

GERENTE

C-SUITE / DIRETOR

ANALISTA

SUPERVISOR

ESTAGIARIO / TRAINEE

ESPECIALISTA

3.3 Área de Atuação

{
  "$filter": {
    "area": "FINANCEIRO"
  }
}

Valores possíveis:

N/A

ADMINISTRATIVO

JURIDICO

ATENDIMENTO AO CLIENTE

RECURSOS HUMANOS

ENGENHARIA

MANUTENCAO

SOCIO

COMPRAS

VENDAS

MARKETING

CONTABILIDADE

OPERACOES

QUALIDADE

INDUSTRIAL

DESENVOLVIMENTO

LOGISTICA

FINANCEIRO

TRANSPORTES

SAUDE, SEGURANCA E MEIO AMBIENTE

DESIGN

PRESIDENCIA

CONSULTORIA

SUPORTE

CONSELHO

INTELIGENCIA DE MERCADO

INFRAESTRUTURA

CYBERSEGURANCA

TECNOLOGIA

CONSTRUCAO

PRODUTOS

NOVOS NEGOCIOS

PLANEJAMENTO FINANCEIRO

AUDITORIA

INOVACAO

PLANEJAMENTO E PERFORMANCE

CONTROLADORIA

COMPLIANCE

DADOS

4. Localização (3 campos)

4.1 Cidade

{
  "$filter": {
    "city": "SAO PAULO"
  }
}

Exemplos de cidades:

"SAO PAULO"

"RIO DE JANEIRO"

"BELO HORIZONTE"

"CURITIBA"

"BRASILIA"

"ARAXA"

4.2 Estado

{
  "$filter": {
    "state": "MINAS GERAIS"
  }
}

Exemplos de estados:

"SAO PAULO"

"RIO DE JANEIRO"

"MINAS GERAIS"

"PARANA"

"RIO GRANDE DO SUL"

"BAHIA"

"SANTA CATARINA"

"DISTRITO FEDERAL"

4.3 País

{
  "$filter": {
    "country": "BRASIL"
  }
}

5. Educação (1 campo)

5.1 Educação

{
  "$filter": {
    "education": { "$fuzzy": "UNIVERSIDADE DE SAO PAULO" }
  }
}

Use $fuzzy para lidar com variações de nome de instituições

Exemplos Práticos Combinados

Exemplo 1: Diretores Financeiros em SP

{
  "$filter": {
    "$and": [
      { "area": "FINANCEIRO" },
      { "seniority": "C-SUITE / DIRETOR" },
      { "state": "SAO PAULO" }
    ]
  }
}

Exemplo 2: Gerentes de RH em empresas específicas

{
  "$filter": {
    "$and": [
      { "area": "RECURSOS HUMANOS" },
      {
        "$or": [{ "seniority": "GERENTE" }, { "seniority": "COORDENADOR" }]
      },
      { "current_company": "AMBEV" }
    ]
  }
}

Exemplo 3: Profissionais de Tecnologia no Sudeste

{
  "$filter": {
    "$and": [
      { "area": "TECNOLOGIA" },
      {
        "$or": [
          { "state": "SAO PAULO" },
          { "state": "RIO DE JANEIRO" },
          { "state": "MINAS GERAIS" },
          { "state": "ESPIRITO SANTO" }
        ]
      },
      {
        "$or": [
          { "seniority": "ESPECIALISTA" },
          { "seniority": "GERENTE" },
          { "seniority": "C-SUITE / DIRETOR" }
        ]
      }
    ]
  }
}

Exemplo 4: C-Level de qualquer área no Brasil

{
  "$filter": {
    "$and": [{ "country": "BRASIL" }, { "seniority": "C-SUITE / DIRETOR" }]
  }
}

Exemplo 5: Profissionais de Vendas em empresa pelo ID

{
  "$filter": {
    "$and": [
      { "current_company_id": 2345678 },
      { "area": "VENDAS" },
      {
        "$or": [
          { "seniority": "GERENTE" },
          { "seniority": "COORDENADOR" },
          { "seniority": "SUPERVISOR" }
        ]
      }
    ]
  }
}

Exemplo 6: Busca por cargo específico com variações

{
  "$filter": {
    "$and": [
      { "current_job_title": { "$fuzzy": "Head de Marketing" } },
      { "country": "BRASIL" }
    ]
  }
}

Exemplo 7: Mapeamento de cargos por múltiplos termos com $fuzzy_in

Útil quando o mesmo papel funcional tem dezenas de variações de título entre empresas diferentes.

{
  "$filter": {
    "$and": [
      {
        "current_company_url": "linkedin.com/company/driva-tech"
      },
      {
        "area": {
          "$in": [
            "COMPRAS",
            "CONTABILIDADE",
            "CONTROLADORIA",
            "FINANCEIRO",
            "PLANEJAMENTO FINANCEIRO",
            "RECURSOS HUMANOS",
            "SOCIO",
            "TECNOLOGIA",
            "INOVACAO"
          ]
        }
      },
      {
        "current_job_title": {
          "$fuzzy_in": [
            "remuneracao",
            "rh",
            "recursos humanos",
            "beneficios",
            "hr",
            "human resources",
            "remuneracao e beneficios",
            "total rewards",
            "salesops",
            "sales ops",
            "sales operations",
            "revops",
            "rev ops",
            "revenue operations"
          ]
        }
      }
    ]
  },
  "$page": 0,
  "$size": 5
}

Neste exemplo, a busca encontra profissionais de uma empresa específica que ocupam áreas estratégicas e cujos cargos correspondem aproximadamente a qualquer um dos termos da lista — cobrindo variações em PT e EN.

Operadores de Comparação

Operadores Gerais

$in: está contido em array de valores

$nin: não está contido em array de valores

$not: negação (inverte a condição)

$exists: campo existe (true/false)

Operadores de Texto

$fuzzy - Busca Aproximada (Fuzzy Search)

Ideal para cargos e nomes com variações ortográficas. Funciona em campos como full_name, current_job_title, current_company, education.

{
  "$filter": {
    "current_job_title": { "$fuzzy": "Analista de Dados" }
  }
}

Este operador encontrará variações como:

"Analista de Dados Senior"

"Analista de Data Analytics"

"Analista Dados"

$fuzzy_in - Busca Aproximada em Lista de Termos

Combina o poder do $fuzzy com um array de termos. O resultado inclui perfis cujo campo corresponde aproximadamente a qualquer um dos termos da lista. Ideal para mapear cargos com nomenclaturas variadas em diferentes empresas.

{
  "$filter": {
    "current_job_title": {
      "$fuzzy_in": ["financeiro", "controller", "fp&a", "controladoria"]
    }
  }
}

Exemplo com $in

{
  "$filter": {
    "seniority": { "$in": ["GERENTE", "C-SUITE / DIRETOR", "COORDENADOR"] }
  }
}

Exemplo com $nin (not in)

{
  "$filter": {
    "seniority": { "$nin": ["ESTAGIARIO / TRAINEE", "OUTROS"] }
  }
}

Exemplo com $not

{
  "$filter": {
    "area": { "$not": "FINANCEIRO" }
  }
}

Profissionais que NÃO são da área Financeira

Exemplo com $exists

{
  "$filter": {
    "education": { "$exists": true }
  }
}

Perfis que possuem informação de educação

Paginação

Além de filtros, você pode controlar a paginação:

{
  "$filter": {},
  "$page": 0,
  "$size": 10
}

Notas Importantes

Campos de texto em maiúsculas: campos como area, seniority, state, city, country e current_company usam valores em MAIÚSCULAS

fuzzy para cargos: o campo current_job_title possui grande variação — prefira sempre $fuzzy para buscas mais abrangentes

ID estável: prefira current_company_id (numérico) ao invés de current_company (texto) para buscas exatas por empresa

Campos nulos: education pode ser vazio — use $exists para verificar preenchimento

Combinação recomendada: sempre combine area + seniority + localização (state ou city) para resultados mais qualificados

Guia de Filtros da API - Consulta Social

Estrutura Básica#

1. Identificação (4 campos)#

1.1 Nome Completo#

1.2 Primeiro Nome#

1.3 Sobrenome#

1.4 ID Público do Perfil#

2. Empresa Atual (3 campos)#

2.1 Nome da Empresa#

2.2 ID da Empresa#

2.3 ID Público da Empresa#

3. Cargo e Área (3 campos)#

3.1 Cargo Atual#

3.2 Senioridade#

3.3 Área de Atuação#

4. Localização (3 campos)#

4.1 Cidade#

4.2 Estado#

4.3 País#

5. Educação (1 campo)#

5.1 Educação#

Exemplos Práticos Combinados#

Exemplo 1: Diretores Financeiros em SP#

Exemplo 2: Gerentes de RH em empresas específicas#

Exemplo 3: Profissionais de Tecnologia no Sudeste#

Exemplo 4: C-Level de qualquer área no Brasil#

Exemplo 5: Profissionais de Vendas em empresa pelo ID#

Exemplo 6: Busca por cargo específico com variações#

Exemplo 7: Mapeamento de cargos por múltiplos termos com $fuzzy_in#

Operadores de Comparação#

Operadores Gerais#

Operadores de Texto#

$fuzzy - Busca Aproximada (Fuzzy Search)#

$fuzzy_in - Busca Aproximada em Lista de Termos#

Exemplo com $in#

Exemplo com $nin (not in)#

Exemplo com $not#

Exemplo com $exists#

Paginação#

Notas Importantes#