API client : recherche, enrichissement et export

Authentification et limites

Créez une clé dans les paramètres de clé API. Son secret n'est affiché qu'une seule fois. Utilisez leads:read pour les lieux, les statuts, les résultats et les exports ; leads:write pour la création de tâches et les actions. Un workflow qui fait les deux a besoin des deux portées. Les anciennes clés n'obtiennent pas automatiquement de portées.

Envoyez Authorization: Bearer sk_YOUR_KEY. Conservez le secret dans un coffre de credentials, jamais dans un workflow ou une URL publique. L'isolation des comptes reste appliquée. L'API D1 de production autorise jusqu'à 60 requêtes par minute et par compte et exige au moins 200 ms entre les requêtes. Jusqu'à trois tâches actives de recherche/campagne/enrichissement partagent le budget de concurrence du compte.

Chaque création de tâche nécessite une Idempotency-Key contenant 8–100 lettres, chiffres, traits de soulignement ou traits d'union. Relancez une requête inchangée avec la même clé. Utilisez une nouvelle clé pour une nouvelle tâche. Le succès renvoie HTTP 202, et non les données terminées.

Découvrir un lieu pris en charge

curl "https://ownerclue.com/api/v1/leads/locations?country=US&type=City&q=Phoenix"   -H "Authorization: Bearer $OWNERCLUE_API_KEY"

Utilisez un code renvoyé ; n'inventez pas de locationCode. Les codes de pays enregistrés incluent US, CA, GB (Royaume-Uni), AU, IE, NZ, SG, DE, FR, ES, IT, NL, MX, BR, PT, AT, CH, BE, ZA et AE (20 pays). Chaque pays doit être activé et disponible pour le compte. GET /api/v1/leads/countries renvoie le tableau des codes disponibles ; ajoutez ?metadata=true pour les noms de pays, les langues et les types de lieux pris en charge. L'espace de travail affiche les mêmes choix disponibles. L'anglais (en) est pris en charge dans ces pays ; le Canada prend également en charge le fr. Les langues de recherche locales sont de pour l'Allemagne et l'Autriche, fr pour la France, es pour l'Espagne et le Mexique, it pour l'Italie, nl pour les Pays-Bas, et pt pour le Brésil et le Portugal. La Suisse prend en charge de/fr/it/en et la Belgique prend en charge nl/fr/de/en. L'Afrique du Sud et les Émirats arabes unis prennent actuellement en charge les recherches en anglais ; les requêtes en arabe et dans d'autres langues locales ne sont pas encore activées. La recherche par mots-clés en langue locale est disponible indépendamment de la correspondance exacte de catégorie, qui nécessite une validation propre au pays et à la langue. La disponibilité d'un pays n'établit pas la qualité des contacts.

Les lieux peuvent être filtrés par type, level=region ou level=city et parentCode. level=city recherche les descendants d'une région sélectionnée, y compris les villes situées sous des comtés ou districts intermédiaires. Cela inclut également les zones locales prises en charge, comme les boroughs britanniques et les quartiers de Singapour. Pour Singapour, type=Country renvoie un code pays directement interrogeable ; la sélection d'une région est facultative.

Le répertoire renvoie un tableau dans data, et non une enveloppe de tâche paginée. Utilisez limit=1–100 (par défaut 50) et offset=0, puis augmentez offset de la longueur renvoyée ; arrêtez-vous lorsqu'une page contient moins de lignes que limit. Exemple : /api/v1/leads/locations?country=GB&level=city&limit=50&offset=50. Remplacez l'origine des exemples par l'origine publique de l'application que vous utilisez.

Créer une recherche, puis interroger

{
  "keyword": "plumber",
  "locationCode": 123456,
  "languageCode": "en",
  "depth": 20
}

Envoyez ce corps en POST à /api/v1/leads/searches avec les deux en-têtes. Le code de lieu ci-dessus est un espace réservé. Une réponse réussie contient code: 0 et data.id. Interrogez GET /api/v1/leads/searches/{id} jusqu'à ce que data.status soit completed. queued/running nécessitent une nouvelle interrogation ; failed nécessite l'examen de l'erreur. N'exportez pas une tâche incomplète.

Routes

Méthode et chemin sous /api/v1/leads	Objectif
GET /countries	Codes pays disponibles ; metadata=true inclut les noms, les langues et les types de lieux
GET /locations	Répertoire de lieux pris en charge ; country, q, type, level, parentCode, limit, offset
GET /searches, /campaigns, /enrichments	Lister les tâches possédées
POST /searches	keyword, locationCode, languageCode, depth ; exactCategory facultatif
POST /campaigns/preview	Prévisualiser les codes de lieux sélectionnés et le nombre maximal estimé de prospects
POST /campaigns	keyword, locations (codes), languageCode, depth, maxLeads
POST /enrichments	rows : [{domain, name?}] ou chaîne csv ; au plus 1,000 lignes
GET /searches/{id}, /campaigns/{id}, /enrichments/{id}	Statut et détails de la tâche
GET /…/{id}/results?limit=100&cursor=…	Résultats et nextCursor
GET /…/{id}/export?format=full	CSV après achèvement
POST /campaigns/{id}/pause, /resume, /stop	Contrôle de la campagne
POST /enrichments/{id}/resume	Reprendre un enrichissement en pause

La profondeur de recherche est de 1–700. La profondeur de campagne accepte 20, 50, 100, 300, 500 ou 700 ; sélectionnez 1–100 codes de lieux et prévisualisez les lieux de recherche étendus avant la création. Les régions se développent en nœuds de recherche locaux pris en charge ; la racine pays de Singapour reste un lieu interrogeable unique. Le guide multi-villes explique l'annulation et la déduplication.

Pagination et filtres

Les listes de tâches et les résultats placent les éléments et nextCursor dans data. Gardez limit constant d'une page à l'autre, transmettez le curseur renvoyé sans le modifier et arrêtez-vous lorsque nextCursor est null. Les résultats peuvent évoluer pendant le traitement, car la pagination utilise actuellement des offsets ; lisez les données finales après achèvement. Les lieux font exception avec un tableau simple.

Les résultats Maps et les exports partagent les filtres q, email=true, owner=true, websiteStatus, signal, phoneType et includeExcluded=true. Les signaux pris en charge sont no_website, website_unreachable, booking_not_found et reviews_below_20. Les formats d'export sont basic, full, gohighlevel, instantly et 1cw. Les résultats d'enrichissement renvoient le résultat de chaque ligne plutôt que les filtres de prospects Maps.

Erreurs et politique de nouvelle tentative

Statut HTTP	Action
202	Enregistrez data.id et interrogez l'état
400	Corrigez l'entrée, la clé d'idempotence, le lieu, le solde de crédits ou la condition de concurrence ; examinez le message
401	Fournissez l'en-tête Bearer
403	Vérifiez la validité de la clé, les portées, la propriété et la disponibilité de l'export
404	Vérifiez l'ID de tâche et le compte
429	Attendez avant de réessayer
503	Capacité indisponible ; réessayez uniquement lorsque sa disponibilité change

Les réponses JSON utilisent {code, message, data} ; les exports CSV renvoient text/csv. Enregistrez à la fois le statut HTTP et le code. Aucun webhook d'achèvement de tâche n'est actuellement disponible ; utilisez le guide d'interrogation n8n. Les règles de facturation s'appliquent de la même manière aux tâches API et aux tâches de l'espace de travail.

Notes, avis et listes

L’interface, les résultats API et les CSV acceptent minRating/maxRating (0–5) et minReviews/maxReviews (entiers positifs ou nuls). Bornes incluses ; les valeurs absentes ne valent pas zéro. Exemple : ?minRating=3.5&maxRating=4.5&minReviews=10&maxReviews=50. Les plages invalides ou inversées sont refusées. Le CSV complet ajoute business_id et des liens de réservation/commande avec sources. Comparer les listes.