> ## 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.

# People Contact Lookup

> Búsqueda inversa de una persona a partir de un correo electrónico, teléfono o nombre/apellido + empresa — sin necesidad de people_search_id. 1 crédito por coincidencia facturable.

La API de People Contact Lookup responde a la pregunta **"¿a quién pertenece este correo electrónico/teléfono/nombre?"** Dale un identificador y obtén de vuelta un `people_search_id` y el perfil de la persona encontrada — sin tener que ejecutar antes una búsqueda.

```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" }'
```

## Cuándo usar Contact Lookup

Usa Contact Lookup cuando **tienes un identificador y quieres encontrar a la persona**:

* Un correo electrónico llegó a tu bandeja de entrada — ¿quién lo envió, de qué empresa, con qué cargo?
* Un número de teléfono llamó a tu línea de ventas — encuéntralo entre tus contactos conocidos
* Un CSV de leads con nombres y empresas pero sin IDs de Pubrio — resuélvelos todos a `people_search_id`
* Un envío de formulario con `email + nombre` — enriquécelo hasta obtener un registro de contacto completo

Si en cambio tienes un `people_search_id` (o una URL de LinkedIn) y quieres el **correo electrónico + teléfono de esa persona**, usa [People Redeem](/es/developer-guides/people-redeem) — es la dirección inversa.

## Dos variantes

| Endpoint                                   | Úsalo cuando                                                                                                  |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| `POST /redeem/people/contact/lookup`       | Búsqueda individual — un identificador por solicitud.                                                         |
| `POST /redeem/people/contact/lookup/batch` | Búsqueda por lotes — hasta el límite de tamaño masivo de tu suscripción por solicitud, procesado en paralelo. |

Ambos endpoints devuelven los mismos metadatos `match` por registro (consulta [Metadatos de coincidencia](#match-metadata) más abajo).

## Inicio 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>

**Respuesta:**

```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 búsqueda

Puedes hacer coincidir a una persona de dos formas:

### Coincidencia exacta — por correo electrónico o teléfono

El modo por defecto. Pasa `email` o `phone`; Pubrio hace coincidir sobre el valor de contacto normalizado. Esto siempre devuelve `match.confidence: "exact"` cuando encuentra coincidencia.

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

```json theme={null}
{ "phone": "+15551234567" }
```

### Coincidencia por similitud — por nombre + dominio o empresa

Si no tienes un identificador determinista, puedes recurrir a la coincidencia por similitud. Pasa `first_name`, `last_name`, más `domain` o `company`, y configura `is_enable_similarity_search: true`.

```json theme={null}
{
  "first_name": "King",
  "last_name": "Lai",
  "domain": "pubrio.com",
  "is_enable_similarity_search": true
}
```

Pubrio primero intenta encontrar una coincidencia exacta de correo/teléfono; si no existe ninguna y la similitud está habilitada, clasifica los candidatos por proximidad de nombre dentro del dominio de la empresa (o, si se omite `domain`, la coincidencia de empresa). Las coincidencias devueltas llevan `match.confidence: "similarity_domain"` o `"similarity_company"` para que puedas filtrar por certeza.

Puedes combinar ambos: pasa un correo electrónico **y** un nombre + dominio. La coincidencia exacta de correo gana; los campos de nombre se convierten en un respaldo solo si el correo no se resuelve.

## Metadatos de coincidencia

Cada registro devuelto incluye un objeto `match` que describe cómo se produjo la coincidencia:

| Campo                      | Valores              | Significado                                                                                                                       |
| -------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `match.confidence`         | `exact`              | Coincidencia directa de correo/teléfono. Máxima confianza.                                                                        |
|                            | `similarity_domain`  | Coincidencia basada en nombre, anclada a un dominio de empresa conocido.                                                          |
|                            | `similarity_company` | Coincidencia basada en nombre, anclada a un nombre de empresa (sin dominio).                                                      |
| `match.input`              | `{ value, type }`    | Repite el identificador que produjo la coincidencia, para que puedas mostrar "coincide con `king.lai@pubrio.com`" en tu interfaz. |
| `match.is_duplicate_input` | boolean              | `true` cuando el mismo identificador apareció antes en un lote — la búsqueda se realiza una sola vez y el duplicado no se cobra.  |

Usa `match.confidence` para condicionar acciones posteriores: por ejemplo, inscribe automáticamente solo las coincidencias `exact` en una secuencia; enruta las coincidencias `similarity_*` a revisión manual.

## Búsqueda por lotes

Envía hasta el límite de tamaño masivo de tu suscripción en una sola solicitud. Cada entrada toma los mismos identificadores que el cuerpo de búsqueda individual.

```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
  }'
```

El lote es síncrono — la respuesta contiene todos los registros resueltos en el mismo orden que la entrada. Las entradas sin coincidencia se eliminan de la respuesta (no aparecen en absoluto y no se cobran).

## Costo en créditos

**1 crédito por coincidencia facturable.** Específicamente:

* Una coincidencia exitosa (exacta o por similitud) → 1 crédito
* Sin coincidencia → 0 créditos
* Entrada duplicada dentro de un lote → 0 créditos (se resuelve una vez, se cobra una vez)

Esto hace que Contact Lookup sea un orden de magnitud más económico que [Redeem](/es/developer-guides/people-redeem) — estás pagando para **identificar** a una persona, no para **desbloquear** sus contactos. Si después de la búsqueda también necesitas su correo/teléfono, canjea el `people_search_id` devuelto.

## Patrones comunes

<CardGroup cols={2}>
  <Card title="Enriquecimiento de correo entrante" icon="envelope-open">
    En cada correo entrante, busca al remitente. Muestra su empresa, cargo y `people_search_id` en tu CRM o vista de helpdesk.
  </Card>

  <Card title="Resolución de CSV a CRM" icon="file-csv">
    Resuelve un CSV de filas `nombre + empresa` a `people_search_id` canónicos. Las que no coinciden de forma exacta reciben automáticamente un intento por similitud.
  </Card>

  <Card title="Enriquecimiento de envío de formulario" icon="form">
    Envía `{ email }` desde tu formulario de marketing. Recibe de vuelta la empresa, el cargo y un ID de Pubrio que puedes enrutar mediante reglas de puntuación.
  </Card>

  <Card title="Pipeline de lookup → redeem" icon="arrow-right-arrow-left">
    Flujo de dos pasos: lookup económico (1 crédito) para identificar a la persona, luego redeem completo (5–10 créditos) solo para las coincidencias por encima de un umbral de confianza.
  </Card>
</CardGroup>

## Preguntas frecuentes

<AccordionGroup>
  <Accordion title="¿Contact Lookup devuelve el correo electrónico y el teléfono verificados?">
    No — Contact Lookup devuelve el perfil de la persona (`people_search_id`, nombre, empresa, dominio, cargo, etc.) más los metadatos de coincidencia. Para obtener los contactos verificados en sí, pasa el `people_search_id` devuelto a [Redeem](/es/developer-guides/people-redeem).
  </Accordion>

  <Accordion title="¿Cuál es la diferencia entre similarity_domain y similarity_company?">
    `similarity_domain` significa que anclamos la coincidencia de nombre a un dominio de empresa conocido — el más fuerte de los niveles de similitud. `similarity_company` significa que la anclamos a un nombre de empresa sin dominio canónico — ligeramente menos confiable, ya que varias empresas no relacionadas pueden compartir un nombre.
  </Accordion>

  <Accordion title="¿Se me cobrará por las entradas sin coincidencia?">
    No. Las entradas sin coincidencia se eliminan silenciosamente de la respuesta y no se facturan.
  </Accordion>

  <Accordion title="¿Qué pasa si envío el mismo correo dos veces en un lote?">
    El duplicado se detecta del lado del servidor, la búsqueda se ejecuta una vez, y se te cobra una vez. La entrada duplicada se marca con `match.is_duplicate_input: true` en la respuesta.
  </Accordion>

  <Accordion title="¿Cuál es el límite de tamaño de lote?">
    El tope está definido en tu suscripción como `people_contact_enrichment_bulk_size`. La mayoría de los planes permiten 100 o más por llamada; contáctanos si necesitas un tope más alto.
  </Accordion>

  <Accordion title="¿Puedo buscar por URL de LinkedIn?">
    No en Contact Lookup. Usa [Redeem](/es/developer-guides/people-redeem) con `linkedin_url` si tienes un perfil de LinkedIn y quieres tanto la resolución como los contactos en una sola llamada.
  </Accordion>

  <Accordion title="¿Qué ocurre con los números de teléfono internacionales?">
    El teléfono se compara sobre una forma normalizada. El formato internacional (E.164) es la entrada más confiable. Los números en formato local pueden coincidir si se puede inferir el país, pero el formato E.164 (`+15551234567`) evita la ambigüedad.
  </Accordion>
</AccordionGroup>

## Relacionado

<CardGroup cols={2}>
  <Card title="People Redeem" icon="key" href="/es/developer-guides/people-redeem">
    Dirección directa: gasta créditos para desbloquear correo electrónico + teléfono de un `people_search_id` o URL de LinkedIn conocido.
  </Card>

  <Card title="People Search" icon="users" href="/es/api-reference/endpoint/people/search">
    Encuentra personas que coincidan con un filtro de empleo/empresa/ubicación.
  </Card>

  <Card title="People Lookup" icon="user" href="/es/api-reference/endpoint/people/lookup">
    Resuelve el perfil completo de una sola persona a partir de un identificador conocido.
  </Card>

  <Card title="Precios" icon="coins" href="/es/get-started/pricing">
    Costos en créditos de todos los endpoints, por nivel de plan.
  </Card>
</CardGroup>