Consulta reversa de contato de pessoas

A API People Contact Lookup responde à pergunta “a quem pertence este e-mail/telefone/nome?” Forneça um identificador e receba de volta um people_search_id e o perfil da pessoa correspondente — sem precisar executar uma busca primeiro.

curl -X POST https://api.pubrio.com/redeem/people/contact/lookup \
  -H "pubrio-api-key: $PUBRIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]" }'

Quando usar o Contact Lookup

Use o Contact Lookup quando você tem um identificador e quer encontrar a pessoa:

Um e-mail chegou na sua caixa de entrada — quem enviou, de qual empresa, com qual cargo?
Um número de telefone ligou para sua linha de vendas — associe-o a um contato conhecido
Um CSV de leads com nomes e empresas, mas sem IDs Pubrio — resolva todos para people_search_ids
Envio de formulário com email + nome — enriqueça em um registro de contato completo

Se, em vez disso, você tem um people_search_id (ou URL do LinkedIn) e quer o e-mail + telefone dessa pessoa, use People Redeem — é a direção inversa.

Duas variantes

Endpoint	Use quando
`POST /redeem/people/contact/lookup`	Consulta única — um identificador por requisição.
`POST /redeem/people/contact/lookup/batch`	Consulta em lote — até o limite de tamanho em massa da sua assinatura por requisição, processado em paralelo.

Ambos os endpoints retornam os mesmos metadados match por registro (veja Metadados de correspondência abaixo).

Início rápido

curl -X POST https://api.pubrio.com/redeem/people/contact/lookup \
  -H "pubrio-api-key: $PUBRIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]" }'

const res = await fetch("https://api.pubrio.com/redeem/people/contact/lookup", {
  method: "POST",
  headers: {
    "pubrio-api-key": process.env.PUBRIO_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "[email protected]" }),
});
const { data } = await res.json();

import os, requests

res = requests.post(
    "https://api.pubrio.com/redeem/people/contact/lookup",
    headers={"pubrio-api-key": os.environ["PUBRIO_API_KEY"]},
    json={"email": "[email protected]"},
)
data = res.json()["data"]

Resposta:

{
  "data": {
    "profile": {
      "credit": 450375,
      "topup_credit": 235236,
      "total_credit_cost": 1
    },
    "peoples": [
      {
        "people_search_id": "e37ccf38-ea8f-422e-9874-cb23b15e8fe4",
        "first_name": "King",
        "last_name": "Lai",
        "people_name": "King Lai",
        "company_name": "Pubrio",
        "domain": "pubrio.com",
        "match": {
          "confidence": "exact",
          "input": { "value": "[email protected]", "type": "email-work" },
          "is_duplicate_input": false
        }
      }
    ]
  }
}

Modos de consulta

Você pode corresponder uma pessoa de duas formas:

Correspondência exata — por e-mail ou telefone

O padrão. Passe email ou phone; a Pubrio faz a correspondência com base no valor de contato normalizado. Isso sempre retorna match.confidence: "exact" quando encontra um resultado.

{ "email": "[email protected]" }

{ "phone": "+15551234567" }

Correspondência por similaridade — por nome + domínio ou empresa

Se você não tem um identificador determinístico, pode recorrer à correspondência por similaridade. Passe first_name, last_name, mais domain ou company, e defina is_enable_similarity_search: true.

{
  "first_name": "King",
  "last_name": "Lai",
  "domain": "pubrio.com",
  "is_enable_similarity_search": true
}

A Pubrio primeiro tenta encontrar uma correspondência exata de e-mail/telefone; se não existir nenhuma e a similaridade estiver ativada, ela classifica os candidatos por proximidade de nome dentro do domínio da empresa (ou, se domain for omitido, pela correspondência de empresa). As correspondências retornadas carregam match.confidence: "similarity_domain" ou "similarity_company", para que você possa filtrar por grau de certeza. Você pode combinar ambos: passar um e-mail e um nome + domínio. A correspondência exata de e-mail prevalece; os campos de nome se tornam um fallback apenas se o e-mail não for resolvido.

Metadados de correspondência

Todo registro retornado inclui um objeto match descrevendo como a correspondência foi feita:

Campo	Valores	Significado
`match.confidence`	`exact`	Correspondência direta de e-mail/telefone. Confiança mais alta.
	`similarity_domain`	Correspondência baseada em nome, ancorada a um domínio de empresa conhecido.
	`similarity_company`	Correspondência baseada em nome, ancorada a um nome de empresa (sem domínio).
`match.input`	`{ value, type }`	Reproduz o identificador que gerou a correspondência, para que você possa mostrar “correspondeu com `[email protected]`” na sua UI.
`match.is_duplicate_input`	boolean	`true` quando o mesmo identificador apareceu antes em um lote — a consulta é feita apenas uma vez e a duplicata não é cobrada.

Use match.confidence para controlar ações posteriores: por exemplo, inscreva automaticamente apenas correspondências exact em uma sequência; encaminhe correspondências similarity_* para revisão manual.

Consulta em lote

Envie até o limite de tamanho em massa da sua assinatura em uma única requisição. Cada entrada aceita os mesmos identificadores do corpo de consulta única.

curl -X POST https://api.pubrio.com/redeem/people/contact/lookup/batch \
  -H "pubrio-api-key: $PUBRIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "peoples": [
      { "email": "[email protected]" },
      { "first_name": "John", "last_name": "Smith", "domain": "example.com" }
    ],
    "is_enable_similarity_search": true
  }'

O lote é síncrono — a resposta contém todos os registros resolvidos na mesma ordem da entrada. Entradas sem correspondência são removidas da resposta (não aparecem de forma alguma e não são cobradas).

Custo em créditos

1 crédito por correspondência cobrável. Especificamente:

Uma correspondência bem-sucedida (exata ou por similaridade) → 1 crédito
Nenhuma correspondência → 0 créditos
Entrada duplicada dentro de um lote → 0 créditos (resolvida uma vez, cobrada uma vez)

Isso torna o Contact Lookup uma ordem de magnitude mais barato que o Redeem — você está pagando para identificar uma pessoa, não para desbloquear seus contatos. Se, depois de consultar, você também precisar do e-mail/telefone, resgate o people_search_id retornado.

Padrões comuns

Enriquecimento de e-mail recebido

A cada e-mail recebido, consulte o remetente. Exiba a empresa, o cargo e o people_search_id na sua visualização de CRM ou helpdesk.

Resolução de CSV para CRM

Resolva um CSV de linhas nome + empresa para people_search_ids canônicos. As que não corresponderem exatamente recebem automaticamente uma tentativa de similaridade.

Enriquecimento de envio de formulário

Passe { email } do seu formulário de marketing. Receba de volta a empresa, o cargo e um ID Pubrio que você pode encaminhar por regras de pontuação.

Pipeline de lookup → redeem

Fluxo em duas etapas: consulta barata (1 crédito) para identificar a pessoa, depois resgate completo (5–10 créditos) apenas para correspondências acima de um limiar de confiança.

Perguntas frequentes

O Contact Lookup retorna e-mail e telefone verificados?

Não — o Contact Lookup retorna o perfil da pessoa (people_search_id, nome, empresa, domínio, cargo etc.) mais os metadados de correspondência. Para obter os contatos verificados propriamente ditos, passe o people_search_id retornado para o Redeem.

Qual a diferença entre similarity_domain e similarity_company?

similarity_domain significa que ancoramos a correspondência de nome a um domínio de empresa conhecido — o nível mais forte de similaridade. similarity_company significa que ancoramos a um nome de empresa sem domínio canônico — ligeiramente menos confiável, já que várias empresas não relacionadas podem compartilhar um nome.

Serei cobrado por entradas sem correspondência?

Não. As entradas sem correspondência são silenciosamente removidas da resposta e não são cobradas.

E se eu enviar o mesmo e-mail duas vezes em um lote?

A duplicata é detectada no lado do servidor, a consulta é executada uma vez, e você é cobrado uma vez. A entrada duplicada é sinalizada com match.is_duplicate_input: true na resposta.

Qual é o limite de tamanho do lote?

O limite é definido na sua assinatura como people_contact_enrichment_bulk_size. A maioria dos planos permite 100+ por chamada; entre em contato se precisar de um limite maior.

Posso consultar por URL do LinkedIn?

Não no Contact Lookup. Use o Redeem com linkedin_url se você tiver um perfil do LinkedIn e quiser tanto a resolução quanto os contatos em uma única chamada.

O que acontece com números de telefone internacionais?

O telefone é correspondido em uma forma normalizada. O formato internacional (E.164) é a entrada mais confiável. Números em formato doméstico podem corresponder se o país puder ser inferido, mas o E.164 (+15551234567) evita ambiguidade.

Relacionados

People Redeem

Direção inversa: gaste créditos para desbloquear e-mail + telefone de um people_search_id ou URL do LinkedIn conhecido.

People Search

Encontre pessoas que correspondam a um filtro de vaga/empresa/localização.

People Lookup

Resolva o perfil completo de uma única pessoa a partir de um identificador conhecido.

Preços

Custos em créditos de todos os endpoints, por nível de plano.

Monitoramento

Busca

Filtros

Pessoas

Expansão

Consulta reversa de contato de pessoas

Quando usar o Contact Lookup

Duas variantes

Início rápido

Modos de consulta

Correspondência exata — por e-mail ou telefone

Correspondência por similaridade — por nome + domínio ou empresa

Metadados de correspondência

Consulta em lote

Custo em créditos

Padrões comuns

Enriquecimento de e-mail recebido

Resolução de CSV para CRM

Enriquecimento de envio de formulário

Pipeline de lookup → redeem

Perguntas frequentes

Relacionados

People Redeem

People Search

People Lookup

Preços

​Quando usar o Contact Lookup

​Duas variantes

​Início rápido

​Modos de consulta

​Correspondência exata — por e-mail ou telefone

​Correspondência por similaridade — por nome + domínio ou empresa

​Metadados de correspondência

​Consulta em lote

​Custo em créditos

​Padrões comuns

Enriquecimento de e-mail recebido

Resolução de CSV para CRM

Enriquecimento de envio de formulário

Pipeline de lookup → redeem

​Perguntas frequentes

​Relacionados

People Redeem

People Search

People Lookup

Preços

Quando usar o Contact Lookup

Duas variantes

Início rápido

Modos de consulta

Correspondência exata — por e-mail ou telefone

Correspondência por similaridade — por nome + domínio ou empresa

Metadados de correspondência

Consulta em lote

Custo em créditos

Padrões comuns

Perguntas frequentes

Relacionados