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

# Recherche de contact par personne

> Retrouvez une personne à partir d'un e-mail, d'un numéro de téléphone ou d'un prénom/nom + entreprise — sans people_search_id requis. 1 crédit par correspondance facturable.

L'API People Contact Lookup répond à la question **« à qui appartient cet e-mail/numéro de téléphone/nom ? »** Fournissez-lui un identifiant, et récupérez en retour un `people_search_id` ainsi que le profil de la personne correspondante — sans avoir à effectuer une recherche au préalable.

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

## Quand utiliser Contact Lookup

Utilisez Contact Lookup lorsque **vous disposez d'un identifiant et souhaitez retrouver la personne** :

* Un e-mail est arrivé dans votre boîte de réception — qui l'a envoyé, pour quelle entreprise, avec quel titre ?
* Un numéro de téléphone a sonné sur votre ligne commerciale — faites-le correspondre à un contact connu
* Un CSV de prospects avec des noms et des entreprises mais sans identifiants Pubrio — résolvez-les tous en `people_search_id`
* Une soumission de formulaire avec `email + name` — enrichissez-la en un enregistrement de contact complet

Si au contraire vous disposez d'un `people_search_id` (ou d'une URL LinkedIn) et souhaitez obtenir **l'e-mail + le téléphone de cette personne**, utilisez [People Redeem](/fr/developer-guides/people-redeem) — c'est le sens inverse.

## Deux variantes

| Endpoint                                   | À utiliser quand                                                                                                |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| `POST /redeem/people/contact/lookup`       | Recherche unique — un identifiant par requête.                                                                  |
| `POST /redeem/people/contact/lookup/batch` | Recherche par lot — jusqu'à la limite de taille en masse de votre abonnement par requête, traitée en parallèle. |

Les deux endpoints renvoient les mêmes métadonnées `match` par enregistrement (voir [Métadonnées de correspondance](#métadonnées-de-correspondance) ci-dessous).

## Démarrage rapide

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

**Réponse :**

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

## Modes de recherche

Vous pouvez faire correspondre une personne de deux façons :

### Correspondance exacte — par e-mail ou téléphone

Le mode par défaut. Passez `email` ou `phone` ; Pubrio effectue la correspondance sur la valeur de contact normalisée. Cela renvoie toujours `match.confidence: "exact"` en cas de succès.

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

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

### Correspondance par similarité — par nom + domaine ou entreprise

Si vous ne disposez pas d'un identifiant déterministe, vous pouvez recourir à la correspondance par similarité. Passez `first_name`, `last_name`, ainsi que `domain` ou `company`, et définissez `is_enable_similarity_search: true`.

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

Pubrio tente d'abord de trouver une correspondance exacte par e-mail/téléphone ; si aucune n'existe et que la similarité est activée, il classe les candidats par proximité de nom au sein du domaine de l'entreprise (ou, si `domain` est omis, de la correspondance d'entreprise). Les correspondances renvoyées portent `match.confidence: "similarity_domain"` ou `"similarity_company"` afin que vous puissiez filtrer selon le degré de certitude.

Vous pouvez combiner les deux : passez un e-mail **et** un nom + domaine. La correspondance exacte par e-mail l'emporte ; les champs de nom ne deviennent un repli que si l'e-mail ne se résout pas.

## Métadonnées de correspondance

Chaque enregistrement renvoyé inclut un objet `match` décrivant la manière dont la correspondance a été établie :

| Champ                      | Valeurs              | Signification                                                                                                                                                      |
| -------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `match.confidence`         | `exact`              | Correspondance directe par e-mail/téléphone. Confiance la plus élevée.                                                                                             |
|                            | `similarity_domain`  | Correspondance basée sur le nom, ancrée à un domaine d'entreprise connu.                                                                                           |
|                            | `similarity_company` | Correspondance basée sur le nom, ancrée à un nom d'entreprise (sans domaine).                                                                                      |
| `match.input`              | `{ value, type }`    | Reprend l'identifiant à l'origine de la correspondance, afin que vous puissiez afficher « correspondance trouvée sur `king.lai@pubrio.com` » dans votre interface. |
| `match.is_duplicate_input` | booléen              | `true` lorsque le même identifiant est déjà apparu plus tôt dans un lot — la recherche n'est effectuée qu'une seule fois et le doublon n'est pas facturé.          |

Utilisez `match.confidence` pour conditionner les actions en aval : par exemple, n'inscrivez automatiquement dans une séquence que les correspondances `exact` ; orientez les correspondances `similarity_*` vers une révision manuelle.

## Recherche par lot

Soumettez jusqu'à la limite de taille en masse de votre abonnement en une seule requête. Chaque entrée reprend les mêmes identifiants que le corps de la recherche unique.

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

Le lot est synchrone — la réponse contient tous les enregistrements résolus dans le même ordre que l'entrée. Les entrées sans correspondance sont supprimées de la réponse (elles n'apparaissent pas du tout et ne sont pas facturées).

## Coût en crédits

**1 crédit par correspondance facturable.** Plus précisément :

* Une correspondance réussie (exacte ou par similarité) → 1 crédit
* Aucune correspondance → 0 crédit
* Entrée en double au sein d'un lot → 0 crédit (résolue une fois, facturée une fois)

Cela rend Contact Lookup nettement moins coûteux que [Redeem](/fr/developer-guides/people-redeem) — vous payez pour **identifier** une personne, pas pour **déverrouiller** ses contacts. Si, après la recherche, vous avez également besoin de son e-mail/téléphone, utilisez le `people_search_id` renvoyé avec Redeem.

## Modèles d'utilisation courants

<CardGroup cols={2}>
  <Card title="Enrichissement des e-mails entrants" icon="envelope-open">
    À chaque e-mail entrant, recherchez l'expéditeur. Affichez son entreprise, son titre et son `people_search_id` dans votre CRM ou votre outil d'assistance.
  </Card>

  <Card title="Résolution CSV vers CRM" icon="file-csv">
    Résolvez un CSV de lignes `name + company` en `people_search_id` canoniques. Celles qui n'obtiennent pas de correspondance exacte bénéficient automatiquement d'une tentative par similarité.
  </Card>

  <Card title="Enrichissement de soumission de formulaire" icon="form">
    Transmettez `{ email }` depuis votre formulaire marketing. Récupérez en retour l'entreprise, le titre et un identifiant Pubrio que vous pouvez faire passer par vos règles de scoring.
  </Card>

  <Card title="Pipeline lookup → redeem" icon="arrow-right-arrow-left">
    Flux en deux étapes : une recherche peu coûteuse (1 crédit) pour identifier la personne, puis un redeem complet (5 à 10 crédits) uniquement pour les correspondances dépassant un seuil de confiance.
  </Card>
</CardGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Contact Lookup renvoie-t-il un e-mail et un téléphone vérifiés ?">
    Non — Contact Lookup renvoie le profil de la personne (`people_search_id`, nom, entreprise, domaine, titre, etc.) ainsi que les métadonnées de correspondance. Pour obtenir les contacts vérifiés eux-mêmes, transmettez le `people_search_id` renvoyé à [Redeem](/fr/developer-guides/people-redeem).
  </Accordion>

  <Accordion title="Quelle est la différence entre similarity_domain et similarity_company ?">
    `similarity_domain` signifie que nous avons ancré la correspondance de nom à un domaine d'entreprise connu — le niveau le plus fiable des paliers de similarité. `similarity_company` signifie que nous avons ancré la correspondance à un nom d'entreprise sans domaine canonique — un peu moins fiable, car plusieurs entreprises sans lien peuvent partager un même nom.
  </Accordion>

  <Accordion title="Serai-je facturé pour les entrées sans correspondance ?">
    Non. Les entrées sans correspondance sont silencieusement supprimées de la réponse et ne sont pas facturées.
  </Accordion>

  <Accordion title="Que se passe-t-il si j'envoie le même e-mail deux fois dans un lot ?">
    Le doublon est détecté côté serveur, la recherche s'exécute une seule fois, et vous n'êtes facturé qu'une seule fois. L'entrée en double est signalée par `match.is_duplicate_input: true` dans la réponse.
  </Accordion>

  <Accordion title="Quelle est la limite de taille des lots ?">
    Le plafond est défini sur votre abonnement en tant que `people_contact_enrichment_bulk_size`. La plupart des offres autorisent 100+ par appel ; contactez-nous si vous avez besoin d'un plafond plus élevé.
  </Accordion>

  <Accordion title="Puis-je rechercher par URL LinkedIn ?">
    Pas avec Contact Lookup. Utilisez [Redeem](/fr/developer-guides/people-redeem) avec `linkedin_url` si vous disposez d'un profil LinkedIn et souhaitez obtenir à la fois la résolution et les contacts en un seul appel.
  </Accordion>

  <Accordion title="Que se passe-t-il avec les numéros de téléphone internationaux ?">
    Le téléphone est mis en correspondance sur une forme normalisée. Le format international (E.164) est l'entrée la plus fiable. Les numéros au format national peuvent correspondre si le pays peut être déduit, mais le format E.164 (`+15551234567`) évite toute ambiguïté.
  </Accordion>
</AccordionGroup>

## Voir aussi

<CardGroup cols={2}>
  <Card title="People Redeem" icon="key" href="/fr/developer-guides/people-redeem">
    Sens inverse : dépensez des crédits pour déverrouiller l'e-mail + le téléphone d'un `people_search_id` connu ou d'une URL LinkedIn.
  </Card>

  <Card title="People Search" icon="users" href="/fr/api-reference/endpoint/people/search">
    Trouvez des personnes correspondant à un filtre d'emploi/entreprise/localisation.
  </Card>

  <Card title="People Lookup" icon="user" href="/fr/api-reference/endpoint/people/lookup">
    Résolvez le profil complet d'une seule personne à partir d'un identifiant connu.
  </Card>

  <Card title="Tarification" icon="coins" href="/fr/get-started/pricing">
    Coûts en crédits pour tous les endpoints, par palier d'offre.
  </Card>
</CardGroup>