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

> Gasta créditos para desbloquear el correo de trabajo, el correo personal y el número de teléfono verificados de una persona que ya has identificado — patrones individual, masivo y masivo asíncrono.

La API de Redeem People convierte un `people_search_id` (o una URL de LinkedIn) en el conjunto completo de contactos verificados — correo de trabajo, correo personal, teléfono — de esa persona. Solo gastas créditos cuando realmente se devuelven datos de contacto.

```bash theme={null}
curl -X POST https://api.pubrio.com/redeem/people \
  -H "pubrio-api-key: $PUBRIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "people_search_id": "e37ccf38-ea8f-422e-9874-cb23b15e8fe4",
    "people_contact_types": ["email-work", "phone"]
  }'
```

## Cuándo usar Redeem

Usa Redeem cuando **ya sabes quién es la persona** y necesitas sus datos de contacto:

* Ejecutaste [People Search](/es/api-reference/endpoint/people/search) y quieres desbloquear los contactos de las coincidencias
* Tienes la URL de un perfil de LinkedIn y quieres contactar a la persona
* Tienes un `people_search_id` de una respuesta anterior de Pubrio

Si en cambio tienes un **correo electrónico o teléfono y quieres encontrar a la persona correspondiente**, usa [People Contact Lookup](/es/developer-guides/people-contact-lookup) — es la dirección inversa y cuesta 1 crédito por coincidencia.

## Tres variantes

| Endpoint                          | Úsalo cuando                      | Comportamiento                                                          |
| --------------------------------- | --------------------------------- | ----------------------------------------------------------------------- |
| `POST /redeem/people`             | Una persona a la vez              | Síncrono. Devuelve los contactos en la respuesta.                       |
| `POST /redeem/people/batch`       | De 2 a N personas de una vez      | Asíncrono. Devuelve un `redeem_query_id` de inmediato.                  |
| `POST /redeem/people/batch/query` | Consultar el resultado de un lote | Devuelve el conjunto de resultados completo cuando el lote se completa. |

El flujo por lotes es el patrón correcto para cualquier flujo de trabajo basado en listas — cargas de CSV, inscripción en secuencias, sincronización con CRM — porque paraleliza el trabajo de resolución de contactos del lado del servidor.

## Inicio rápido — redeem individual

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.pubrio.com/redeem/people \
    -H "pubrio-api-key: $PUBRIO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "people_search_id": "e37ccf38-ea8f-422e-9874-cb23b15e8fe4",
      "people_contact_types": ["email-work", "phone"]
    }'
  ```

  ```js JavaScript theme={null}
  const res = await fetch("https://api.pubrio.com/redeem/people", {
    method: "POST",
    headers: {
      "pubrio-api-key": process.env.PUBRIO_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      people_search_id: "e37ccf38-ea8f-422e-9874-cb23b15e8fe4",
      people_contact_types: ["email-work", "phone"],
    }),
  });
  const { data } = await res.json();
  ```

  ```python Python theme={null}
  import os, requests

  res = requests.post(
      "https://api.pubrio.com/redeem/people",
      headers={"pubrio-api-key": os.environ["PUBRIO_API_KEY"]},
      json={
          "people_search_id": "e37ccf38-ea8f-422e-9874-cb23b15e8fe4",
          "people_contact_types": ["email-work", "phone"],
      },
  )
  data = res.json()["data"]
  ```
</CodeGroup>

**Respuesta:**

```json theme={null}
{
  "data": {
    "profile": {
      "credit": 450376,
      "topup_credit": 235237,
      "total_credit_cost": 15
    },
    "peoples": [
      {
        "people_search_id": "e37ccf38-ea8f-422e-9874-cb23b15e8fe4",
        "emails": [
          { "value": "king.lai@pubrio.com", "type": "email-work", "status": "Verified" }
        ],
        "phones": [
          { "value": "+15551234567", "type": "phone", "status": null }
        ]
      }
    ]
  }
}
```

`profile` refleja tu saldo posterior al cargo y los créditos que costó esta llamada, para que puedas actualizar un medidor dentro de tu app sin una llamada adicional a `/profile/usage`.

## Identificadores

Puedes identificar a la persona a canjear de dos formas:

| Identificador      | Descripción                                                                                                                                                                                                                 |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `people_search_id` | UUID devuelto por cualquier endpoint de búsqueda/lookup de Pubrio. El más económico y confiable — sin paso de resolución.                                                                                                   |
| `linkedin_url`     | Una URL de perfil de LinkedIn (p. ej., `https://www.linkedin.com/in/jane-doe-123`). Pubrio primero la resuelve a un `people_search_id`; si el perfil es nuevo, esto puede incluir un paso de enriquecimiento externo único. |

`people_contact_types` es el contrato de lo que quieres recibir de vuelta. Combina cualquiera de `email-work`, `email-personal`, `phone` — se te cobra por tipo devuelto, no por tipo solicitado. Pedir `["email-work", "phone"]` y recibir solo `email-work` te cobra únicamente el correo.

## Redeem masivo (patrón asíncrono)

Para más de una persona, usa el flujo por lotes. Ejecuta cada redeem en paralelo del lado del servidor y evita el costo de ida y vuelta por solicitud.

**Paso 1 — enviar:**

```bash theme={null}
curl -X POST https://api.pubrio.com/redeem/people/batch \
  -H "pubrio-api-key: $PUBRIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "peoples": [
      "540574d1-ff74-475b-aea2-f8ae643b806d",
      "e37ccf38-ea8f-422e-9874-cb23b15e8fe4"
    ],
    "people_contact_types": ["email-work", "phone"]
  }'
```

```json theme={null}
{
  "data": {
    "redeem_query_id": "a046c1da-b3d4-4ca1-aca6-1dd8c8055701",
    "is_completed": false,
    "estimated_time": 6,
    "estimated_time_type": "second"
  }
}
```

**Paso 2 — consultar:**

```bash theme={null}
curl -X POST https://api.pubrio.com/redeem/people/batch/query \
  -H "pubrio-api-key: $PUBRIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "redeem_query_id": "a046c1da-b3d4-4ca1-aca6-1dd8c8055701" }'
```

Cuando `is_completed` es `true`, la respuesta contiene el array `peoples` completo con los contactos resueltos y el costo total en créditos del lote.

<Tip>
  Consulta con la cadencia indicada por `estimated_time`. Consultar con más frecuencia que la estimada solo desperdicia idas y vueltas — el trabajo aún no está terminado.
</Tip>

## Costos en créditos

Los créditos se descuentan **por contacto devuelto**, no por solicitud. Precios por registro:

| Tipo de contacto                | Créditos por registro |
| ------------------------------- | --------------------- |
| `email-work` / `email-personal` | 5                     |
| `phone`                         | 10                    |

Si una persona no tiene correo de trabajo y solo solicitaste `email-work`, no se te cobra nada por ese registro. Si solicitaste tanto un correo como un teléfono y Pubrio devuelve ambos, se te cobra por ambos. Consulta la [tabla de precios](/es/get-started/pricing) completa para tarifas específicas por plan.

## Patrones comunes

<CardGroup cols={2}>
  <Card title="Pipeline de search → redeem" icon="magnifying-glass">
    Ejecuta [People Search](/es/api-reference/endpoint/people/search), deja que el usuario elija filas en tu interfaz, y luego envía los `people_search_id` seleccionados a través de `/redeem/people/batch`. Cobra solo por lo que se usa.
  </Card>

  <Card title="Flujo de pegado de URLs de LinkedIn" icon="linkedin">
    Acepta una lista de URLs de LinkedIn desde una exportación de CRM o una extensión de navegador. Envíalas mediante `/redeem/people` (individual) o construye un pequeño wrapper por lotes.
  </Card>

  <Card title="Inscripción en secuencias" icon="envelope">
    Antes de agregar contactos a una cadencia de salida, canjea solo `email-work` — mantiene el costo predecible mientras alimenta direcciones entregables a tu remitente.
  </Card>

  <Card title="Enriquecimiento de CRM" icon="database">
    Mapea registros existentes de CRM a `people_search_id` (mediante [People Lookup](/es/api-reference/endpoint/people/lookup)), y luego canjea por lotes de forma programada.
  </Card>
</CardGroup>

## Preguntas frecuentes

<AccordionGroup>
  <Accordion title="¿Se me cobrará si no se encuentra ningún contacto?">
    No. Los créditos se descuentan por registro devuelto. Si una persona no tiene correo de trabajo disponible, no pagas nada por ese espacio de contacto — incluso si lo solicitaste.
  </Accordion>

  <Accordion title="¿Qué pasa si la misma persona está dos veces en mi lote?">
    Los duplicados se eliminan del lado del servidor. Se te cobra una sola vez.
  </Accordion>

  <Accordion title="¿Qué ocurre si la URL de LinkedIn es desconocida para Pubrio?">
    Pubrio intenta una resolución externa única. Si el perfil se resuelve, se aplica el precio normal de redeem. Si no se resuelve, no se cobran créditos.
  </Accordion>

  <Accordion title="¿Qué tan actualizados están los datos de contacto?">
    Pubrio revalida los registros de correo y teléfono de forma continua. Cada contacto incluye un campo `status` (`Verified`, `null`, etc.) para que puedas filtrar solo los registros verificados de tu lado.
  </Accordion>

  <Accordion title="¿Puedo canjear solo teléfono, solo correo, o solo correo personal?">
    Sí — `people_contact_types` es un array. Pasa exactamente los tipos que quieres; solo se te factura por lo que se devuelve.
  </Accordion>

  <Accordion title="Masivo frente a individual — ¿cuándo gana el patrón asíncrono?">
    Por encima de \~3 registros, el lote gana en latencia y en fiabilidad por registro. El endpoint de lotes ejecuta el fan-out internamente y paraleliza cualquier salto de enriquecimiento externo, por lo que un lote de 50 registros se acerca más a 5 segundos de tiempo real que a 50 × el RTT por solicitud.
  </Accordion>
</AccordionGroup>

## Relacionado

<CardGroup cols={2}>
  <Card title="People Contact Lookup" icon="magnifying-glass-arrow-right" href="/es/developer-guides/people-contact-lookup">
    Búsqueda inversa: encuentra a una persona a partir de un correo electrónico, teléfono o nombre + dominio. 1 crédito por coincidencia.
  </Card>

  <Card title="People Search" icon="users" href="/es/api-reference/endpoint/people/search">
    Encuentra personas que coincidan con un perfil (cargo, ubicación, tamaño de empresa, tecnologías, etc.).
  </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 — sin desbloqueo de contacto.
  </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>