---
title: "Enrichir en masse (jusqu’à 10 000 contacts)"
method: POST
path: "/search/bulk"
tags: ["Person Enrichment"]
---

# Enrichir en masse (jusqu’à 10 000 contacts)

`POST /search/bulk`

## Request

- Base URL: `https://api.listar.fr`
- URL: `https://api.listar.fr/search/bulk`
- Auth: HTTP bearer

Soumet jusqu’à 10 000 contacts en un seul appel. Réponse **202** immédiate avec un `id` de batch ; les contacts sont enrichis en arrière-plan. Le résultat complet est poussé sur votre `callbackUrl` (webhook signé `batch_enrichment.completed`) - aucun polling requis. Facturé par donnée trouvée sur votre solde crédit, débité à la fin du batch.

## Request body

- object
  - `contacts` object[], required: Liste de contacts (1 à 10 000). Chaque contact requiert au moins un critère identifiant (firstName, lastName, fullName, email, phone, linkedinUrl, linkedinSlug, doctolibSlug ou rppsId). Plus l’identifiant est fort, plus la livraison est ancrée : un simple nom + zone ne suffit pas à livrer un datapoint.
    - `ref` string: Identifiant client, ré-échoué dans la sortie.
    - `firstName` string
    - `lastName` string
    - `fullName` string
    - `company` string
    - `city` string
    - `postalCode` string: Code postal EXACT - active l'ancre `acceptGeoExactUnique` (mobile ou email sur nom + code postal exact).
    - `country` string
    - `jobTitle` string
    - `email` string
    - `phone` string
    - `linkedinUrl` string
    - `linkedinSlug` string
    - `doctolibSlug` string: Chemin de fiche Doctolib (`<specialite>/<ville>/<praticien>`, ex. `medecin-generaliste/paris/jean-dupont`) ou URL complète de la fiche. Son portrait sert de photo de RÉFÉRENCE au face match - souvent la seule ancre disponible sur un praticien libéral sans LinkedIn. Sa spécialité sert aussi de contexte anti-homonyme quand `jobTitle` est absent.
    - `rppsId` string: Identifiant national RPPS (11 chiffres). ANCRE FORTE : une fiche de l'annuaire officiel partageant ce RPPS désigne la personne sans ambiguïté d'homonyme.
    - `industry` string
    - `website` string
  - `options` object: Au moins un canal parmi `searchPhone`, `searchProEmail` et `searchPersoEmail` doit rester à `true` (400 sinon).
    - `searchPhone` boolean: **Activé par défaut** : sans `options`, les téléphones trouvés sont livrés ET facturés. Passer `false` pour un batch email seul.
    - `searchProEmail` boolean
    - `searchPersoEmail` boolean
    - `includeSharedEmails` boolean: Livrer aussi les boîtes PARTAGÉES d'entreprise (`contact@`, `accueil@`, `pharmacieX@…`) en plus des emails nominatifs. Désactivé par défaut (précision d'abord) : n'activez que si les adresses d'établissement vous conviennent.
    - `acceptGeoExactUnique` boolean: Livrer les mobiles ET les emails corroborés par `nom + CODE POSTAL EXACT` quand un SEUL est trouvé à ce code postal. L’unicité est comptée canal par canal : ≥2 mobiles distincts au même CP = homonymes → mobile non livré, sans effet sur l’email, et réciproquement. Les fixes en restent exclus. Élargit la couverture sur les listes géo-précises (gérants, professions libérales) ; la géo lâche (ville / rayon) reste insuffisante. **Désactivé par défaut** (opt-in) - risque de fuite homonyme si le code postal est PARTAGÉ (siège / arrondissement) et que la cible n’a pas la donnée en base. Passer `true` pour l’activer sur des listes où le CP est le domicile/commune d’exercice réel.
    - `requirePersonalEmailProof` boolean: Ne livrer (et ne facturer) un email PERSONNEL que sur PREUVE d'appartenance : face match entre la photo du compte (Gravatar / GitHub / Google / Teams) et le portrait de référence du contact, ou ancre qui désigne la personne elle-même (RPPS, slug LinkedIn fourni, email ou téléphone d'entrée partagé). Une adresse perso n'est rattachée ni à une société ni à une ville : sans cette option, elle peut être livrée sur une simple corroboration de l'entourage. **Désactivé par défaut** (opt-in) - l'activer réduit le volume d'emails perso livrés.
  - `callbackUrl` string, uri, required: URL https notifiée à la fin du batch (webhook signé). **Requis** - unique canal de restitution du résultat.

## Response `202`

Batch accepté. Le résultat complet arrivera par webhook `batch_enrichment.completed`.

- object
  - `success` boolean
  - `id` string
  - `totalContacts` integer
  - `status` string

## Other responses

- `402`: Crédit insuffisant pour le coût max estimé.
- `422`: Plus de 10 000 contacts dans le batch.
- `429`: Trop de requêtes (60 / min par clé API). `Retry-After` donne le délai d’attente.

---

[API](https://skmtc.dev/listar/apis/listar-api.md) · [All operations](https://skmtc.dev/listar/apis/listar-api/llms.txt) · [OpenAPI document](https://skmtc.dev/listar/apis/listar-api/revisions/d8b4a5e9acc8?raw)