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 points d'accès passent pour « l'API Clay » sans l'être : la colonne HTTP, une source webhook entrante, un webhook sortant signé, une action native de fournisseur, le serveur MCP. Chacun a son offre minimale et ses propres plafonds. Et quand Clay décrit un comportement sans publier le moindre chiffre, la page le signale.

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 changé 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 sa propre entrée dans le changelog, ce qui explique en partie pourquoi la réponse périmée reste si bien classée. Ce qui suit, c'est le câblage : ce qui crée des lignes, ce qui remplit des cellules, ce à quoi votre code a accès, 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. Chaque appel s'authentifie 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. L'API expose 13 opérations : vérification d'identité, exécution de routines, jobs en lot, Searches et lecture de tables. Avec une clé refusée, elle renvoie {"message": "Authentication failed"}. Les clés doivent rester côté serveur.

Le fichier est lisible par une machine, ce qui permet de générer votre client automatiquement : openapi.json déclare un info.title « Clay Public API », un info.version « 0 » et un seul schéma d'authentification, ClayApiKey. Pas d'openapi.yaml.

Les intégrations Clay : dix points d'accès, 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 libellés « il nous faut l'API Clay » réclament en réalité une source ou une colonne. La différence pèse lourd : d'un côté un sprint de développement, de l'autre un simple changement d'offre.

Avant de bâtir quoi que ce soit sur ce dernier bloc, sachez que Clay se contredit. 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 travail équivalent réalisé dans l'application ». La FAQ tarifaire, elle, classe « 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 tirées 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 tourne sur les offres actuelles ainsi que sur les anciennes offres jusqu'à fin 2026.

Launch est à 185 $/mois, 167 $ en facturation annuelle ; Growth à 495 $, 446 $ en annuel. Clay publie ses prix en dollars et je les laisse tels quels ; le détail des paliers est dans les tarifs Clay. Le répertoire de fournisseurs, lui, change de taille selon l'endroit où on le compte : « 200+ providers » dans la navigation du site, « 150+ data partners » dans la FAQ tarifaire, et 157 URL /integrations/data-provider/ uniques, réparties sur 24 catégories, quand je les ai comptées sur clay.com/integrations le 29 août.

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 — Clay a intitulé sa page de référence « Execute a routine against 1-100 items », le plafond est donc dans le titre. Clay répond 202 avec un routine_run_id, et accepte un webhook_id optionnel.

Les gros jobs demandent quatre appels : demandez 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 réunit 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 la limite des plafonds du tableau plus bas. Si vous en dépassez un, Clay renvoie un HTTP 402 qui indique lequel. 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 n'énonce en première page de Google. Clay écrit n'avoir, « pour l'instant, aucun projet 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 n'entrent pas du tout — pour savoir dans quel ordre monter cette partie, voyez comment utiliser Clay.

Ce que Clay vous dit quand un appel échoue

Clay documente en détail son comportement en cas d'échec, mais ne publie aucun chiffre sur le seuil à partir duquel il bride les appels. Tenez-en compte avant de dimensionner un job.

Quand le workspace atteint sa limite de débit, vous recevez un HTTP 429, un 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 le code de sortie 4. Le conseil de Clay : considérer qu'un 429 peut être réessayé, et « préférer les endpoints en lot et asynchrones aux boucles de polling trop rapproché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 d'erreurs doit donc s'appuyer sur le 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 passagères. Dernier point, et il en piège beaucoup : un 202 sur un endpoint asynchrone n'est pas un succès. Il veut dire que le job tourne encore.

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

Avec cette colonne, Clay appelle un outil 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) : l'exemple donné par Clay, 10 requêtes sur 1 000 ms, revient à dix requêtes par seconde.

Clay fait lui-même deux mises en garde sur les identifiants. 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 attention, 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 ; en dessous d'Enterprise, il faut créer une nouvelle source. Le guide porte encore le badge d'une offre « Explorer » qui ne figure plus sur la page des 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 ; ils 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 type LinkedIn partent en général de Find People, dans la limite des plafonds du tableau plus bas, auxquels s'ajoutent des exclusions de 300 000 personnes 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 révèlent des coordonnées. Clay for Chrome récupère les données structurées d'une page et mappe vers une table 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 4,4 sur 5 pour 9 avis, 10 000 utilisateurs, 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 exactement 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 : d'après la doc développeur de Clay, il apporte les skills Clay et la CLI clay à des agents de code 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 valent 50 000. Celle qui doit vraiment guider votre architecture, c'est 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. » Les solutions proposées par Clay : découper le fichier par filtre ou par plage de dates, ou passer aux tables à suppression automatique et à l'enrichissement en masse sur Enterprise.

Ajouter une colonne Enrow à 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 étiquetée « Included in All Plans ». Trois actions s'utilisent sous forme de colonnes, et chacune renvoie un statut de qualification avec le résultat.

Notre propre documentation indique un coût en crédits Clay pour cette vérification, alors que la fiche Clay la présente comme gratuite. Vérifiez dans l'application avant de compter dessus. Si vous utilisez votre propre clé, configurez une colonne HTTP API qui appelle 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 l'identifiant de recherche sur l'endpoint GET correspondant jusqu'à obtenir le résultat. Réglez Request limit sur 10 et Duration sur 1000 pour respecter la limite d'Enrow : chaque endpoint POST autorise dix requêtes par seconde et par clé, et un POST en lot compte pour une seule requête, même s'il contient 5 000 emails.

Voici ce qui compte dans une chaîne d'enrichissement qui relance ses requêtes. La règle de Clay : « 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 si un résultat valide revient, jamais en cas d'échec. Quand un résultat revient, un email coûte 1 crédit Enrow, un numéro de portable 40 et une vérification un quart de crédit, le tout décompté d'un solde unique. L'ordre des sources est traité dans les waterfalls d'enrichissement Clay.

Chaque adresse passe plus de dix vérifications, et les domaines catch-all reçoivent un verdict net plutôt qu'une étiquette « risqué ». 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 retrouve 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 accompagné d'informations sur l'entreprise. Il n'y a pas de base à parcourir derrière : une requête comme « 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 faite 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 manque ne vous coûte rien, parce que Find People, une synchro CRM ou un CSV font déjà ce travail en amont — comment choisir un fournisseur de données B2B pose les critères.

Si votre pipeline est écrit en code plutôt que monté dans un workbook, vous appelez les mêmes recherches directement. L'API d'Enrow vous donne 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é, avec leur code source 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 est dans l'API email finder.

FAQ

L'API de Clay est-elle gratuite ?

La plateforme développeur n'ajoute aucun surcoût. La doc de Clay indique 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 même travail fait dans l'application. 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 le point d'accès 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 indique que « HTTP API integrations » et « Automate any signal via webhooks » ne sont inclus ni dans Free ni dans Launch, et place les connexions CRM et data warehouse au même palier. L'API publique, la CLI et le serveur MCP tournent 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, pour l'instant, aucun projet permettant de construire des 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. En dessous d'Enterprise, la solution consiste à en créer une nouvelle ; 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 donc votre workspace, listez ce que vous faites tourner pour de vrai, 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 votre 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, pour l'application, l'extension Chrome et les assistants IA. Brancher votre propre clé Enrow sur la colonne passe par l'API, ouverte dès le premier achat : un forfait à partir de 15 €/mois ou un pack de crédits sans abonnement.