API Clay et intégrations : ce qui entre, ce qui sort, ce qu'on câble soi-même

À retenir Clay a bien une API publique : https://api.clay.com/public/v0, un en-tête clay-api-key, 13 opérations documentées et un fichier OpenAPI 3.1.0 de 67 151 octets, disponible sur developers.clay.com/openapi.json (consulté le 29 août 2026). Cinq autres éléments passent pour « l'API Clay » sans en être : la colonne HTTP, une source webhook entrante, un webhook sortant signé, une action de fournisseur native, le serveur MCP. Chacun a son offre minimale et ses propres plafonds. Et quand Clay décrit un comportement sans publier le moindre chiffre, c'est signalé ici.

Un responsable RevOps m'a transféré le mois dernier un article de blog, comme preuve que Clay n'avait pas d'API. Beaucoup de pages le disent encore. Elles décrivent un produit qui a évolué depuis : l'URL de base est publique, et le fichier de spécification se télécharge sans accroc. Je l'ai récupéré le 29 août — 67 151 octets, OpenAPI 3.1.0, 13 opérations.

La plateforme développeur n'a jamais eu droit à une entrée dans le changelog, et c'est une des raisons pour lesquelles l'ancienne réponse reste bien classée dans Google. Voici le câblage : ce qui crée des lignes, ce qui remplit des cellules, ce que votre code peut appeler, et tous les plafonds publiés.

Clay a-t-il une API ?

Oui. L'API publique de Clay se trouve sur https://api.clay.com/public/v0. L'authentification passe par un en-tête clay-api-key, avec une clé générée dans Settings → Account → API keys (la section porte encore la mention beta), et l'API expose 13 opérations : vérification d'identité, exécution de routines, jobs en lot, Searches et lecture de tables. Une clé refusée renvoie {"message": "Authentication failed"}. Gardez les clés côté serveur.

Le fichier est lisible par une machine : vous pouvez donc générer votre client automatiquement. La spécification openapi.json déclare un info.title « Clay Public API », un info.version « 0 » et un seul schéma, ClayApiKey. Il n'existe pas d'openapi.yaml.

Les intégrations Clay : dix points de connexion, et comment savoir lequel vous concerne

Les lignes entrent par une source, ou elles n'entrent pas : l'API publique lit les tables, sans jamais en construire.

La plupart des tickets du type « il nous faut l'API Clay » portent en réalité sur une source ou une colonne. Selon le cas, la réponse va d'un sprint de développement à un simple changement d'offre.

La documentation se contredit sur un point, à garder en tête avant de bâtir quoi que ce soit sur les dernières lignes du tableau. university.clay.com/docs/clay-api-cli écrit que la plateforme développeur est « disponible sur toutes les offres Clay, y compris les offres gratuites et d'essai », et que les appels API et CLI consomment « les mêmes crédits et actions que le même travail réalisé dans le produit ». La FAQ tarifaire, elle, place « Clay API access » parmi les avantages du plan Enterprise, et le tableau comparatif ne contient aucune ligne API. Vérifiez d'abord dans votre propre workspace. Deux précisions de la même doc : la CLI et l'API sont prises en charge sur Mac et Linux en beta ouverte, pas sur Windows, et la beta de l'Agent Plugin fonctionne sur les offres actuelles ainsi que sur les anciennes offres jusqu'à fin 2026.

Launch est à 185 $/mois, 167 $ en facturation annuelle ; Growth à 495 $, ou 446 $ en annuel. Clay publie ses prix en dollars et je les laisse tels quels ; le détail des paliers figure dans notre article sur les tarifs Clay. Le répertoire de fournisseurs de Clay se décline en trois chiffres différents : « 200+ providers » dans la navigation du site, « 150+ data partners » dans la FAQ tarifaire, et 157 URL /integrations/data-provider/ uniques quand je les ai comptées sur clay.com/integrations le 29 août, réparties sur 24 catégories.

Les routines : l'unité de travail que votre code peut appeler

Une routine, c'est de la logique Clay à laquelle on a donné une adresse : vous construisez une fonction personnalisée dans l'interface, vous activez son intégration API, vous récupérez l'identifiant t_... et vous le préfixez par function:.

Les petits jobs s'exécutent en direct. POST /routines/{routine_id}/run accepte un tableau items de 1 élément minimum et 100 maximum. Le plafond figure jusque dans le titre de la page de référence : « Execute a routine against 1-100 items ». Clay répond 202 avec un routine_run_id, et accepte un webhook_id optionnel.

Les gros jobs demandent quatre appels : réclamez une URL présignée à run-batch/upload-url, envoyez le JSONL en PUT avec le type application/x-ndjson et des lignes de la forme {"id": "row-1", "inputs": {"domain": "clay.com"}}, faites un POST sur run-batch/start, puis un GET /routines/run-batch/{id}/results. La CLI regroupe les quatre en une seule commande, clay routines runs start function:t_abc123 --bulk rows.jsonl, et clay login --device vous authentifie sur une machine sans navigateur.

Searches interroge la base GTM propriétaire de Clay, en recherche avancée (beta, booléens imbriqués) ou par filtres structurés, dans les limites du tableau plus bas. Si vous en dépassez une, Clay renvoie une erreur HTTP 402 qui l'indique. Une réserve : university.clay.com/docs/clay-api-cli affiche 10 000 résultats par requête sur les offres payantes en self-serve, là où developers.clay.com/searches en affiche 500. Je retiens la doc développeur.

Et voici la limite que personne ne mentionne dans les premiers résultats de Google. Clay écrit n'avoir « aucun projet actuel de permettre la construction de tables via la plateforme développeur ». Tables est en lecture seule, réservé à Enterprise, interrogeable sur POST /public/v0/tables/query, sans endpoint pour lister les tables. Les lignes entrent par une source, ou elles n'entrent pas ; pour construire une table dans le bon ordre, voyez notre article sur l'utilisation de Clay.

Ce que Clay vous dit quand un appel échoue

Clay documente très correctement son comportement en cas d'échec, mais ne publie aucun chiffre sur le seuil de bridage. Tenez-en compte avant de dimensionner un job.

En cas de dépassement de la limite de débit par workspace, vous recevez une erreur HTTP 429, un en-tête Retry-After en secondes, et les en-têtes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset « quand ils sont disponibles ». La CLI, elle, renvoie un code de sortie 4. Clay conseille de traiter le 429 comme une erreur temporaire, à réessayer, et de « préférer les endpoints en lot et asynchrones aux boucles de polling serrées ».

Les réponses hors 2xx sont du JSON avec un champ message lisible par un humain. Clay précise que « les corps de réponse d'erreur ne contiennent pas, pour l'instant, de codes d'erreur stables ». Votre gestion des erreurs doit donc s'appuyer sur le code de statut : 401 et 403 pour l'authentification, 404 pour une ressource introuvable, 409 et 422 pour la validation, 429 pour le débit, 5xx pour les erreurs transitoires. Dernier point, et il en piège beaucoup : un 202 sur un endpoint asynchrone n'est pas un succès. Il signifie seulement que le traitement est en cours.

La colonne HTTP API : brancher une source dont Clay n'a jamais entendu parler

Avec cette colonne, Clay peut appeler un service absent de son répertoire : elle « vous permet d'envoyer ou de récupérer des données depuis n'importe quel outil ou base de données via un endpoint d'API, même quand Clay ne propose pas d'intégration native », en GET, POST, PUT et DELETE. Tous les codes de statut que Clay documente ici décrivent l'endpoint que vous avez appelé, pas Clay. C'est de ce côté-là qu'il faut chercher quand une colonne passe au rouge.

La dernière ligne inverse la répartition habituelle : le bridage, c'est à vous de le régler, pas à Clay de vous l'imposer. Deux champs suffisent, Request limit et Duration (ms), et l'exemple donné par Clay, 10 sur 1 000 ms, revient à dix requêtes par seconde.

Deux avertissements sur les identifiants, venus de Clay lui-même. Une clé tapée dans le champ Headers est « visible en clair par toute personne ayant accès à la colonne de la table » : passez donc par un compte enregistré. Mais modifier ce compte « affectera toutes les colonnes d'enrichissement HTTP API de votre workspace qui l'utilisent ».

Les webhooks Clay vont dans les deux sens et n'ont que le nom en commun

Vider la table ne remet pas le compteur des 50 000 envois à zéro, et un webhook sortant peut ne jamais arriver.

Le webhook entrant est une source : cliquez sur + Add en bas d'un workbook, cherchez Webhooks, choisissez Monitor webhook, copiez l'URL. Le jeton d'authentification ne s'affiche qu'une fois — « copiez bien le jeton immédiatement, les jetons d'authentification ne sont accessibles qu'une seule fois ». Vient ensuite le plafond qui piège les équipes : une source webhook accepte 50 000 envois, et ce compteur « persiste même après suppression des lignes ». Vider la table ne change rien ; sur les offres inférieures à Enterprise, il faut créer une nouvelle source. Le guide affiche encore un badge pour une offre « Explorer » qui ne figure plus sur la page de tarifs — vérifiez donc le palier dans votre propre workspace.

Le webhook sortant, lui, relève de la plateforme développeur. clay webhooks create https://example.com/hooks/clay renvoie un id, une url, un createdAt et un signingSecret qu'il faut « stocker immédiatement, il ne peut pas être récupéré ensuite ». Les payloads contiennent webhookId, createdAt et un objet data, et sont signés par un en-tête X-Clay-Signature: sha256= suivi d'un HMAC-SHA256 calculé sur le corps. Et voici la phrase qui devrait dicter votre architecture, pas seulement votre gestion d'erreurs : « La livraison des webhooks n'est pas garantie. Servez-vous des webhooks pour réagir plus vite, mais continuez à interroger les résultats du run en secours. »

Clay et LinkedIn : les limites de Find People, et ce que fait vraiment l'extension Chrome

Les listes de profils façon LinkedIn partent en général de Find People, dans les limites du tableau plus bas. S'y ajoutent des exclusions, plafonnées à 300 000 personnes au total et à 100 000 par source, réparties sur trois ensembles et rapprochées par URL LinkedIn. La documentation de Clay ne nomme jamais la source de données qui alimente tout ça. Je ne la nommerai pas non plus.

C'est sur l'extension Chrome que les gens se trompent le plus souvent, alors disons-le simplement : la documentation de Clay présente ses deux extensions comme des outils d'extraction, pas comme des outils qui trouvent des coordonnées. Clay for Chrome récupère les données structurées d'une page et les range dans une table, avec des champs comme le nom, le site, LinkedIn ou Crunchbase. Clip to Clay enregistre des pages entières. La fiche de Clay for Chrome sur le Chrome Web Store affiche une note de 4,4 sur 5 (9 avis) et 10 000 utilisateurs ; il s'agit de la version 1.0.0, mise à jour le 10 avril 2025.

Clay MCP : votre workspace dans un assistant

Le serveur MCP de Clay relie un workspace à Claude, ChatGPT, Microsoft Copilot et Glean, et s'administre dans Settings → MCP users. Les contrôles de crédits sont disponibles sur Launch, Growth et Enterprise ; les contrôles d'audience restent réservés à Enterprise. La facturation est identique à celle du produit : « Si une Function qui trouve l'email et le numéro de téléphone d'une personne coûte 12 crédits dans une table Clay, elle coûte 12 crédits quand un commercial la déclenche depuis Claude ou ChatGPT. » L'Agent Plugin est encore autre chose : selon la doc développeur de Clay, il fournit les skills Clay et la CLI clay à des agents de programmation comme Claude Code, Codex et Cursor. Il s'utilise donc dans un terminal, pas dans un client de chat.

Tous les plafonds que Clay met par écrit

Presque toutes les limites de Clay sont fixées à 50 000, et celle qui doit vraiment guider votre conception concerne la source webhook, parce que son compteur survit à la suppression des lignes.

L'enrichissement en masse au-delà de 50 000 enregistrements est réservé à Enterprise. Et une phrase de la doc « sources » mérite d'être lue avant tout gros import : une fois la limite de lignes atteinte, « Clay importe les enregistrements jusqu'à la limite puis s'arrête automatiquement. Aucun message d'erreur ne s'affiche. » Clay propose deux solutions : découper le fichier par filtre ou par plage de dates, ou passer aux tables à suppression automatique et à l'enrichissement en masse sur Enterprise.

Donner une colonne à Enrow dans votre table

Ni Clay ni Enrow ne facturent une recherche vide : une chaîne qui réessaie ne paie que les résultats obtenus.

Enrow figure dans le répertoire de Clay depuis le 1er septembre 2024, dans les catégories Contact Data et Contact Data Verification, avec une intégration développée par Clay et signalée comme « Included in All Plans ». Trois actions s'utilisent comme des colonnes, et chacune renvoie un statut de qualification en plus du résultat.

Notre propre documentation indique un coût en crédits Clay sur cette vérification, alors que la fiche Clay la présente comme gratuite. Vérifiez dans l'application avant de compter dessus. Avec votre propre clé Enrow, configurez une colonne HTTP API sur https://api.enrow.io/email/find/single, avec les en-têtes x-api-key et Content-Type: application/json et le corps {"company_domain": /company_domain, "fullname": "/first_name /last_name"}. La réponse est asynchrone : passez une URL de webhook Clay dans settings.webhook, ou interrogez le GET correspondant avec l'identifiant de recherche jusqu'à obtenir une réponse. Réglez Request limit sur 10 et Duration sur 1000 pour rester dans les limites : chaque endpoint POST d'Enrow autorise dix requêtes par seconde et par clé, et un POST en lot compte pour une seule requête, même quand il contient 5 000 emails.

Voici maintenant le point décisif pour une chaîne qui réessaie. La règle de Clay est la suivante : « si un enrichissement ne renvoie aucun résultat, vous n'êtes facturé ni en Data Credits ni en Actions ». La nôtre dit la même chose, côté fournisseur : un crédit n'est débité que pour un résultat valide, jamais pour un échec, jamais pour un bounce. Quand un résultat est trouvé, un email coûte 1 crédit Enrow, un numéro de portable 40, une vérification un quart de crédit, le tout sur un compteur unique. L'ordre des sources est traité dans notre article sur l'enrichissement en cascade dans Clay.

Chaque adresse passe plus de dix vérifications, les domaines catch-all reçoivent un verdict net plutôt qu'une étiquette « risqué », et les numéros de portable européens sont accompagnés de leur documentation RGPD. Le taux de couverture tourne autour de 60 % et le taux de bounce reste sous 1 % sur nos propres fichiers — des mesures que nous relevons, jamais des chiffres que nous promettons.

La liste qu'Enrow ne construira pas pour vous

Enrow trouve les coordonnées de personnes que vous avez déjà identifiées. Pour un email, il faut un nom complet et un domaine ; pour un numéro de portable, une URL de profil, ou un nom avec le contexte de l'entreprise. Il n'y a pas de base à parcourir, donc une requête du type « tous les VP Engineering d'Amsterdam dans des boîtes en série B » ne renvoie rien. C'est un choix assumé. Une ligne stockée se périme sans prévenir, une recherche en temps réel non, et je préfère renoncer à la fonction de recherche plutôt que d'en proposer une qui vieillit mal. Dans Clay, ce n'est pas un handicap, parce que Find People, une synchro CRM ou un CSV font déjà ce travail en amont ; les critères pour choisir un fournisseur sont détaillés dans comment choisir un fournisseur de données B2B.

Si votre pipeline est du code plutôt qu'un workbook, les mêmes recherches sont accessibles directement. Pour l'API d'Enrow, vous obtenez une clé sans passer par un commercial, avec des SDK officiels dans sept langages — JS/TypeScript, Python, PHP, Go, Java, Swift, Rust — tous en accès anticipé, à installer depuis les sources sur GitHub. Le serveur MCP EnrowAPI/enrow-mcp met ces trois mêmes recherches à la disposition d'un assistant : Claude ou Cursor trouvent les coordonnées d'un contact sans passer par une table. Le détail des endpoints figure dans notre article sur les API de recherche d'emails.

FAQ

L'API de Clay est-elle gratuite ?

La plateforme développeur n'ajoute aucun surcoût. La doc de Clay écrit qu'elle est disponible sur toutes les offres, y compris les offres gratuites et d'essai, et que les appels API et CLI consomment les mêmes crédits et actions que le travail fait dans le produit. Ce qui vous limite vraiment, ce sont les 500 actions et les 100 data credits par mois du plan Free.

Quelle différence entre l'API HTTP de Clay et son API publique ?

Elles fonctionnent en sens inverse. L'API HTTP est une colonne à l'intérieur d'une table Clay : elle appelle un endpoint tiers et écrit la réponse dans une ligne, et le tableau comparatif de Clay la réserve au plan Growth. L'API publique, sur https://api.clay.com/public/v0, est l'interface que votre propre code appelle depuis l'extérieur de Clay, pour exécuter des routines, lancer des jobs en lot et interroger Searches.

Quelle offre faut-il pour l'API HTTP et les webhooks de Clay ?

Growth. Le tableau comparatif de Clay marque « HTTP API integrations » et « Automate any signal via webhooks » comme non inclus sur Free et sur Launch, et place les connexions CRM et data warehouse au même palier. L'API publique, la CLI et le serveur MCP sont disponibles sur toutes les offres, selon la doc développeur.

Quelles sont les limites de débit de l'API Clay ?

Clay publie le comportement, pas le chiffre. L'API publique applique une limite de requêtes par workspace, renvoie une erreur HTTP 429, envoie un Retry-After en secondes et ajoute X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset quand ils sont disponibles. Aucune valeur en requêtes par seconde n'apparaît dans la documentation.

Peut-on écrire des données dans une table Clay via l'API ?

Non. Clay indique n'avoir aucun projet actuel de permettre la construction de tables via la plateforme développeur. Tables est en lecture seule, réservé à Enterprise, et s'interroge sur POST /public/v0/tables/query avec une taille de page plafonnée à 100 lignes. Les lignes entrent par une source.

Y a-t-il une limite de webhooks dans Clay ?

Oui, et elle est définitive. Une source webhook Clay accepte 50 000 envois, et Clay précise que cette limite « persiste même après suppression des lignes » : vider la table ne remet rien à zéro. Sur les offres inférieures à Enterprise, la solution consiste à créer une nouvelle source ; Enterprise lève le plafond avec les tables à suppression automatique.

Que fait l'extension Chrome de Clay ?

Elle récupère le contenu de pages web, elle ne trouve pas de coordonnées. Clay for Chrome extrait les données structurées d'une page web, d'une liste détectée automatiquement ou d'un profil individuel, vers une table Clay, avec des champs comme le nom, le site, LinkedIn, Twitter ou Crunchbase. Clip to Clay, la seconde extension, enregistre des pages web entières dans une table.

Clay a-t-il un serveur MCP ?

Oui. Il relie un workspace à Claude, ChatGPT, Microsoft Copilot et Glean, se gère dans Settings → MCP users, avec des contrôles de crédits à partir de Launch et un compteur de dépense remis à zéro le 1er de chaque mois, à minuit UTC. Clay ne facture aucun supplément MCP : 12 crédits dans une table, c'est 12 crédits depuis un assistant.

Ouvrez votre workspace, listez ce que vous utilisez réellement, et rangez chaque élément dans une ligne du premier tableau. La réponse à « est-ce qu'on peut automatiser ça » se trouve presque toujours déjà dans le compte, un palier plus haut ou une colonne plus loin.

Et si ce qui vous manque, c'est un email vérifié ou un numéro de portable européen, Enrow est dans le répertoire, sous forme de colonne que vous pouvez activer dès aujourd'hui. L'offre gratuite vous donne 50 crédits au début de chaque mois, indéfiniment, sans jamais demander de carte bancaire.