> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pubrio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Consulta reversa de contato de pessoas

> Faça a busca reversa de uma pessoa a partir de um e-mail, telefone ou nome/sobrenome + empresa — sem necessidade de people_search_id. 1 crédito por correspondência cobrável.

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.

```bash theme={null}
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": "king.lai@pubrio.com" }'
```

## 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_id`s
* 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](/pt/developer-guides/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](#match-metadata) abaixo).

## Início rápido

<CodeGroup>
  ```bash curl theme={null}
  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": "king.lai@pubrio.com" }'
  ```

  ```js JavaScript theme={null}
  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: "king.lai@pubrio.com" }),
  });
  const { data } = await res.json();
  ```

  ```python Python theme={null}
  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": "king.lai@pubrio.com"},
  )
  data = res.json()["data"]
  ```
</CodeGroup>

**Resposta:**

```json theme={null}
{
  "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": "king.lai@pubrio.com", "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.

```json theme={null}
{ "email": "king.lai@pubrio.com" }
```

```json theme={null}
{ "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`.

```json theme={null}
{
  "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 `king.lai@pubrio.com`" 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.

```bash theme={null}
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": "king.lai@pubrio.com" },
      { "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](/pt/developer-guides/people-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

<CardGroup cols={2}>
  <Card title="Enriquecimento de e-mail recebido" icon="envelope-open">
    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.
  </Card>

  <Card title="Resolução de CSV para CRM" icon="file-csv">
    Resolva um CSV de linhas `nome + empresa` para `people_search_id`s canônicos. As que não corresponderem exatamente recebem automaticamente uma tentativa de similaridade.
  </Card>

  <Card title="Enriquecimento de envio de formulário" icon="form">
    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.
  </Card>

  <Card title="Pipeline de lookup → redeem" icon="arrow-right-arrow-left">
    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.
  </Card>
</CardGroup>

## Perguntas frequentes

<AccordionGroup>
  <Accordion title="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](/pt/developer-guides/people-redeem).
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Posso consultar por URL do LinkedIn?">
    Não no Contact Lookup. Use o [Redeem](/pt/developer-guides/people-redeem) com `linkedin_url` se você tiver um perfil do LinkedIn e quiser tanto a resolução quanto os contatos em uma única chamada.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Relacionados

<CardGroup cols={2}>
  <Card title="People Redeem" icon="key" href="/pt/developer-guides/people-redeem">
    Direção inversa: gaste créditos para desbloquear e-mail + telefone de um `people_search_id` ou URL do LinkedIn conhecido.
  </Card>

  <Card title="People Search" icon="users" href="/pt/api-reference/endpoint/people/search">
    Encontre pessoas que correspondam a um filtro de vaga/empresa/localização.
  </Card>

  <Card title="People Lookup" icon="user" href="/pt/api-reference/endpoint/people/lookup">
    Resolva o perfil completo de uma única pessoa a partir de um identificador conhecido.
  </Card>

  <Card title="Preços" icon="coins" href="/pt/get-started/pricing">
    Custos em créditos de todos os endpoints, por nível de plano.
  </Card>
</CardGroup>