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, en ligne sur developers.clay.com/openapi.json le 29 août 2026. Cinq autres choses se font appeler « 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. Chacune a son offre minimale et ses propres plafonds. Et quand Clay décrit un comportement sans publier le moindre chiffre, c'est écrit 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 bougé 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 à son entrée de changelog, et c'est une des raisons pour lesquelles la vieille réponse continue de bien se classer. Ce qui suit, c'est le câblage : ce qui crée des lignes, ce qui remplit des cellules, ce que votre code peut atteindre, et tous les plafonds publiés.

Clay a-t-il une API ?

Oui. L'API publique de Clay vit sur https://api.clay.com/public/v0. Elle s'authentifie avec un en-tête clay-api-key, généré dans Settings → Account → API keys — la section porte encore la mention beta — et 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"}. Les clés restent côté serveur.

Le fichier est lisible par une machine, donc votre client peut se générer tout seul : openapi.json déclare un info.title « Clay Public API », un info.version « 0 » et un unique schéma ClayApiKey. Pas d'openapi.yaml.

Les intégrations Clay : dix surfaces, et comment savoir laquelle 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 rédigés « il nous faut l'API Clay » demandent en réalité une source ou une colonne. Entre les deux, l'écart va d'un sprint de dev à un simple changement d'offre.

Un désaccord à garder en tête avant de bâtir quoi que ce soit sur ce dernier bloc. 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, range « Clay API access » dans les puces 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 tourne 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 $. Clay publie ses prix en dollars et je les laisse tels quels ; le détail des paliers est dans les tarifs Clay. Clay compte son répertoire de fournisseurs de trois façons différentes : « 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 passent 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 : 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 plie 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, sous les plafonds du tableau plus bas. Dépassez-en un et Clay renvoie un HTTP 402 qui le nomme. 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 « 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 — l'ordre de construction de ce côté-là est dans comment utiliser Clay.

Ce que Clay vous dit quand un appel échoue

Clay documente très correctement son comportement en cas d'échec, et ne publie aucun chiffre sur le seuil de bridage. Réglez ce point avant de dimensionner un job.

Vous récupérez un HTTP 429 sur une limite de débit par workspace, 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, remonte un code de sortie 4. Le conseil de Clay : traiter le 429 comme réessayable, et « 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 aiguillage se fait donc sur le statut : 401 et 403 pour l'authentification, 404 pour l'introuvable, 409 et 422 pour la validation, 429 pour le débit, 5xx pour le transitoire. Dernier point, et il en piège beaucoup : un 202 sur un endpoint asynchrone n'est pas un succès. Ça veut dire que ça tourne encore.

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

Cette colonne permet à Clay d'appeler quelque chose qui ne figure pas dans 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, et ils viennent de Clay. 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é. Sauf que 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 rend aucun des 50 000 envois, et un webhook sortant peut ne jamais arriver.

Le webhook entrant est une source : + Add en bas d'un workbook, cherchez Webhooks, choisissez Monitor webhook, copiez l'URL. Le jeton d'authentification ne se montre 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, vous en montez une nouvelle. Le guide affiche encore un badge pour une offre « Explorer » qui ne figure plus sur la page tarifs — vérifiez donc le palier dans votre propre workspace.

Le sortant, lui, appartient à 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 portent webhookId, createdAt et un objet data, 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

C'est par Find People que commencent en général les listes qui ressemblent à du LinkedIn, sous les 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 appariées sur les 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 des champs comme le nom, le site, LinkedIn ou Crunchbase dans une table. 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 arrivent sur Launch, Growth et Enterprise ; les contrôles d'audience restent réservés à Enterprise. La facturation colle exactement au 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 : la doc développeur de Clay le décrit comme livrant les skills Clay et la CLI clay à des agents de code comme Claude Code, Codex et Cursor. Il vit 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, et celle qui doit vraiment guider votre conception est la source webhook, parce que son compteur survit à la suppression.

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 : arrivé à la limite de lignes, « Clay importe les enregistrements jusqu'à la limite puis s'arrête automatiquement. Aucun message d'erreur ne s'affiche. » Les remèdes que propose 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.

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 ce qui revient.

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 construite par Clay et étiquetée « Included in All Plans ». Trois actions tournent comme des colonnes, et chacune renvoie un statut de qualification à côté du résultat.

Notre propre documentation indique un coût en crédits Clay sur cette vérification, là où la fiche Clay la donne gratuite. Vérifiez dans l'application avant de compter dessus. Avec votre propre clé, configurez une colonne HTTP API sur https://api.enrow.io/email/find/single, en-têtes x-api-key et Content-Type: application/json, 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 le GET correspondant jusqu'à ce qu'il réponde. Réglez Request limit sur 10 et Duration sur 1000 pour être raccord : 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 transporte 5 000 emails.

Voilà maintenant le point qui compte dans une chaîne qui réessaie. 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 depuis le côté fournisseur : un crédit quitte le compteur quand un résultat valide revient, jamais sur un échec, jamais sur un bounce. Quand quelque chose revient, 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 les waterfalls d'enrichissement Clay.

Derrière chaque adresse, il y a plus de dix vérifications, des domaines catch-all résolus et livrés au lieu d'être estampillés « risqué », et des numéros de portable européens accompagnés de leur documentation RGPD. Le taux de découverte tourne autour de 60 % et le 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 résout des personnes que vous avez déjà identifiées. Un email demande un nom complet et un domaine ; un numéro de portable demande une URL de profil, ou un nom avec le contexte de l'entreprise. Il n'y a rien derrière à parcourir, donc « tous les VP Engineering d'Amsterdam dans des boîtes en série B » revient vide. C'est un choix assumé. Une ligne stockée se périme sans prévenir, une résolution en temps réel non, et je préfère renoncer à la fonction de recherche plutôt que d'en livrer une qui vieillit mal. Dans Clay, ça 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 du code plutôt qu'un workbook, les mêmes recherches répondent en direct. L'API d'Enrow délivre 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é, depuis les sources sur GitHub. Le serveur MCP EnrowAPI/enrow-mcp place les trois mêmes recherches derrière un assistant : Claude ou Cursor résolvent un contact sans table entre les deux. 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 é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 ?

Les deux regardent dans des directions opposées. 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 la surface 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 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 un 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 et réservé à Enterprise, 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 documente 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 scrape des pages, elle ne révèle 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, en mappant 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 une dépense qui se remet à 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 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 aujourd'hui. L'offre gratuite vous donne 50 crédits au début de chaque mois, indéfiniment, sans jamais demander de carte bancaire.