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

> Gaste créditos para desbloquear e-mail de trabalho verificado, e-mail pessoal e telefone de uma pessoa que você já identificou — padrões individual, em lote e em lote assíncrono.

A API Redeem People transforma um `people_search_id` (ou URL do LinkedIn) no conjunto completo de contatos verificados — e-mail de trabalho, e-mail pessoal, telefone — dessa pessoa. Você só gasta créditos quando os dados de contato são de fato retornados.

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

## Quando usar o Redeem

Use o Redeem quando **você já sabe quem é a pessoa** e precisa dos dados de contato dela:

* Você executou o [People Search](/pt/api-reference/endpoint/people/search) e quer desbloquear os contatos das correspondências
* Você tem a URL de um perfil do LinkedIn e quer entrar em contato com a pessoa
* Você tem um `people_search_id` de uma resposta anterior da Pubrio

Se, em vez disso, você tem um **e-mail ou telefone e quer encontrar a pessoa correspondente**, use o [People Contact Lookup](/pt/developer-guides/people-contact-lookup) — é a direção inversa, e custa 1 crédito por correspondência.

## Três variantes

| Endpoint                          | Use quando                      | Comportamento                                                        |
| --------------------------------- | ------------------------------- | -------------------------------------------------------------------- |
| `POST /redeem/people`             | Uma pessoa por vez              | Síncrono. Retorna os contatos na resposta.                           |
| `POST /redeem/people/batch`       | 2 a N pessoas de uma vez        | Assíncrono. Retorna um `redeem_query_id` imediatamente.              |
| `POST /redeem/people/batch/query` | Polling para resultados em lote | Retorna o conjunto completo de resultados quando o lote é concluído. |

O fluxo em lote é o padrão certo para qualquer workflow orientado por listas — uploads de CSV, inscrição em sequências, sincronização de CRM — porque paraleliza o trabalho de resolução de contatos no lado do servidor.

## Início 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>

**Resposta:**

```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` reproduz seu saldo após a cobrança e os créditos que esta chamada custou, para que você possa atualizar um medidor no seu app sem uma chamada separada a `/profile/usage`.

## Identificadores

Você pode identificar a pessoa a resgatar de duas formas:

| Identificador      | Descrição                                                                                                                                                                                                                   |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `people_search_id` | UUID retornado por qualquer endpoint de busca/consulta da Pubrio. Mais barato e mais confiável — sem etapa de resolução.                                                                                                    |
| `linkedin_url`     | Uma URL de perfil do LinkedIn (ex.: `https://www.linkedin.com/in/jane-doe-123`). A Pubrio a resolve primeiro para um `people_search_id`; se o perfil for novo, isso pode incluir uma etapa única de enriquecimento externo. |

`people_contact_types` é o contrato do que você quer receber de volta. Combine quaisquer valores entre `email-work`, `email-personal`, `phone` — você é cobrado por tipo retornado, não por tipo solicitado. Pedir `["email-work", "phone"]` e receber de volta apenas `email-work` cobra apenas pelo e-mail.

## Redeem em massa (padrão assíncrono)

Para mais de uma pessoa, use o fluxo em lote. Ele executa cada redeem em paralelo no lado do servidor e evita o custo de ida e volta por requisição.

**Etapa 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"
  }
}
```

**Etapa 2 — consultar (polling):**

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

Quando `is_completed` for `true`, a resposta conterá o array `peoples` completo com os contatos resolvidos e o custo total em créditos do lote.

<Tip>
  Faça o polling na cadência informada por `estimated_time`. Fazer polling mais frequente do que a estimativa apenas desperdiça idas e voltas — o trabalho ainda não terminou.
</Tip>

## Custos em créditos

Os créditos são deduzidos **por contato retornado**, não por requisição. Preço por registro:

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

Se uma pessoa não tem e-mail de trabalho e você solicitou apenas `email-work`, você não é cobrado por esse registro. Se você solicitou tanto um e-mail quanto um telefone e a Pubrio retorna ambos, você é cobrado por ambos. Veja a [tabela de preços](/pt/get-started/pricing) completa para taxas específicas por plano.

## Padrões comuns

<CardGroup cols={2}>
  <Card title="Pipeline de busca → redeem" icon="magnifying-glass">
    Execute o [People Search](/pt/api-reference/endpoint/people/search), deixe o usuário selecionar linhas na sua UI e então envie os `people_search_id`s selecionados via `/redeem/people/batch`. Cobre apenas pelo que for usado.
  </Card>

  <Card title="Fluxo de colar URLs do LinkedIn" icon="linkedin">
    Aceite uma lista de URLs do LinkedIn de uma exportação de CRM ou extensão de navegador. Envie-as via `/redeem/people` (individual) ou monte um pequeno wrapper de lote.
  </Card>

  <Card title="Inscrição em sequências" icon="envelope">
    Antes de adicionar contatos a uma cadência de saída, resgate apenas `email-work` — mantém o custo previsível enquanto alimenta seu remetente com endereços entregáveis.
  </Card>

  <Card title="Enriquecimento de CRM" icon="database">
    Mapeie registros existentes do CRM para `people_search_id` (via [People Lookup](/pt/api-reference/endpoint/people/lookup)), depois resgate em lote de forma programada.
  </Card>
</CardGroup>

## Perguntas frequentes

<AccordionGroup>
  <Accordion title="Serei cobrado se nenhum contato for encontrado?">
    Não. Os créditos são deduzidos por registro retornado. Se uma pessoa não tem e-mail de trabalho disponível, você não paga nada por esse slot de contato — mesmo que o tenha solicitado.
  </Accordion>

  <Accordion title="E se a mesma pessoa aparecer duas vezes no meu lote?">
    As duplicatas são deduplicadas no lado do servidor. Você é cobrado uma vez.
  </Accordion>

  <Accordion title="O que acontece se a URL do LinkedIn for desconhecida pela Pubrio?">
    A Pubrio tenta uma resolução externa única. Se o perfil for resolvido, o preço normal de redeem se aplica. Se não for, nenhum crédito é cobrado.
  </Accordion>

  <Accordion title="Quão atualizados são os dados de contato?">
    A Pubrio reverifica registros de e-mail e telefone de forma contínua. Cada contato vem com um campo `status` (`Verified`, `null` etc.), para que você possa filtrar apenas registros verificados no seu lado.
  </Accordion>

  <Accordion title="Posso resgatar apenas telefone, apenas e-mail ou apenas e-mail pessoal?">
    Sim — `people_contact_types` é um array. Passe exatamente os tipos que deseja; você só é cobrado pelo que for retornado.
  </Accordion>

  <Accordion title="Em lote vs. individual — quando o padrão assíncrono vale mais a pena?">
    Acima de \~3 registros, o lote leva vantagem em latência e em confiabilidade por registro. O endpoint de lote executa fan-out internamente e paraleliza qualquer etapa de enriquecimento externo, então um lote de 50 registros fica mais perto de 5 segundos de tempo total do que 50 × o RTT por requisição.
  </Accordion>
</AccordionGroup>

## Relacionados

<CardGroup cols={2}>
  <Card title="People Contact Lookup" icon="magnifying-glass-arrow-right" href="/pt/developer-guides/people-contact-lookup">
    Consulta reversa: encontre uma pessoa a partir de um e-mail, telefone ou nome + domínio. 1 crédito por correspondência.
  </Card>

  <Card title="People Search" icon="users" href="/pt/api-reference/endpoint/people/search">
    Encontre pessoas que correspondam a um perfil (cargo, localização, tamanho de empresa, tecnologias etc.).
  </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 — sem desbloqueio de contato.
  </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>