En résumé : Cette page de référence regroupe l’ensemble des endpoints de l’API Rodz, les limites de débit, les codes d’erreur, le format des réponses et la pagination. Gardez-la en favori. C’est le document à consulter chaque fois que vous intégrez un endpoint ou que vous déboguez un appel.
Qu’est-ce que la référence API Rodz ?
La référence API Rodz est le document technique central qui décrit tous les points d’accès disponibles pour interagir avec la plateforme Rodz par programmation. Elle couvre trois grandes familles de fonctionnalités : les signaux d’affaires, l’enrichissement de données et les webhooks.
Contrairement aux guides pas-à-pas qui vous accompagnent dans un cas d’usage précis, cette page de référence adopte une approche exhaustive. Chaque endpoint est documenté avec sa méthode HTTP, son chemin, ses paramètres et son comportement attendu. Vous y trouverez aussi les règles de gestion des erreurs, les limites de débit et le fonctionnement de la pagination.
Ce document s’adresse aux développeurs qui intègrent Rodz dans leur stack technique, aux équipes ops qui automatisent leurs workflows commerciaux et aux architectes qui conçoivent des pipelines de données. Si vous cherchez plutôt une introduction progressive, commencez par le guide de démarrage avec l’authentification et votre première requête.
Prérequis
Avant de plonger dans les endpoints, assurez-vous d’avoir les éléments suivants :
- Un compte Rodz actif avec un plan incluant l’accès API. Créez votre compte sur app.rodz.io si ce n’est pas encore fait.
- Une clé API valide générée depuis votre tableau de bord. Le guide de démarrage explique la procédure complète.
- Un outil pour effectuer des requêtes HTTP : cURL, Postman, Insomnia ou le client HTTP de votre langage de programmation.
- Une compréhension de base du format JSON pour lire les réponses et construire les corps de requête.
- Les notions de signaux d’affaires et d’enrichissement de données. Consultez le guide des signaux d’affaires et le guide de l’enrichissement pour vous mettre à niveau.
Base URL et authentification
Base URL
Toutes les requêtes vers l’API Rodz utilisent la même URL de base :
https://api.rodz.io/v1Chaque endpoint documenté dans cette page est relatif à cette base. Par exemple, l’endpoint /signals/feed correspond à l’URL complète https://api.rodz.io/v1/signals/feed.
L’API utilise exclusivement le protocole HTTPS. Les requêtes en HTTP simple sont rejetées.
Authentification
L’API Rodz utilise l’authentification par Bearer token. Incluez votre clé API dans l’en-tête Authorization de chaque requête :
curl -X GET https://api.rodz.io/v1/signals/feed \
-H "Authorization: Bearer VOTRE_CLE_API" \
-H "Content-Type: application/json"Quelques règles importantes :
- Ne partagez jamais votre clé API dans du code côté client ou dans des dépôts publics.
- Stockez votre clé dans une variable d’environnement ou un gestionnaire de secrets.
- Si vous pensez que votre clé a été compromise, régénérez-la immédiatement depuis votre tableau de bord.
Pour un guide détaillé sur l’authentification, la rotation des clés et les bonnes pratiques de sécurité, consultez l’article dédié à l’authentification.
Endpoints Signaux d’affaires
Les signaux d’affaires constituent le coeur de la plateforme Rodz. Ces endpoints vous permettent de consulter les types de signaux disponibles, de créer et gérer vos configurations, puis de récupérer les signaux détectés.
Pour comprendre en profondeur ce que sont les signaux d’affaires et comment les utiliser en prospection, lisez le guide complet des signaux d’affaires.
| Méthode | Endpoint | Description |
|---|---|---|
| GET | /signals/types | Liste des 14 types de signaux |
| POST | /signals/configurations | Créer une configuration |
| GET | /signals/configurations | Lister vos configurations |
| GET | /signals/configurations/:id | Détail d’une configuration |
| PUT | /signals/configurations/:id | Modifier une configuration |
| DELETE | /signals/configurations/:id | Supprimer une configuration |
| GET | /signals/feed | Récupérer vos signaux |
GET /signals/types
Retourne la liste complète des 14 types de signaux disponibles sur la plateforme. Chaque type inclut son identifiant unique, son nom, sa description et les filtres applicables. Utilisez cette liste pour choisir les signaux pertinents avant de créer une configuration.
Cet endpoint ne nécessite aucun paramètre. La réponse est identique pour tous les utilisateurs.
POST /signals/configurations
Crée une nouvelle configuration de signaux. Le corps de la requête doit contenir le type de signal, les critères de ciblage (secteur, zone géographique, taille d’entreprise) et la fréquence souhaitée.
Pour un tutoriel étape par étape, consultez le guide Configurer votre premier signal d’affaires via l’API.
{
"signal_type": "fundraising",
"filters": {
"country": "FR",
"industry": ["saas", "fintech"],
"employee_range": { "min": 10, "max": 500 }
},
"frequency": "daily"
}GET /signals/configurations
Retourne toutes vos configurations actives. Supporte la pagination (voir la section Pagination plus bas). Vous pouvez filtrer par type de signal avec le paramètre signal_type.
GET /signals/configurations/:id
Retourne le détail d’une configuration spécifique, y compris ses statistiques d’utilisation : nombre de signaux générés, dernier signal détecté, date de création et de dernière modification.
PUT /signals/configurations/:id
Modifie une configuration existante. Vous pouvez mettre à jour les filtres, la fréquence ou le statut (actif/inactif). Le corps de la requête suit le même format que la création, mais seuls les champs fournis sont modifiés.
DELETE /signals/configurations/:id
Supprime définitivement une configuration. Les signaux déjà générés restent accessibles dans votre feed, mais aucun nouveau signal ne sera détecté pour cette configuration.
GET /signals/feed
Récupère les signaux détectés selon vos configurations actives. C’est l’endpoint que vous interrogerez le plus souvent. Il supporte la pagination par curseur et plusieurs paramètres de filtrage :
configuration_id: filtrer par configuration spécifiquesignal_type: filtrer par type de signalsince: date de début (format ISO 8601)until: date de fin (format ISO 8601)cursor: curseur de paginationlimit: nombre de résultats par page (défaut 50, max 200)
Endpoints Enrichissement
L’enrichissement de données vous permet de compléter les informations sur un contact ou une entreprise à partir d’un identifiant minimal (nom, domaine, email, numéro SIREN). Chaque endpoint est spécialisé dans un type de données.
Pour une vue d’ensemble de l’enrichissement et de ses cas d’usage, consultez le guide de l’enrichissement de données.
| Méthode | Endpoint | Description |
|---|---|---|
| POST | /enrich/contact | Enrichir un contact |
| POST | /enrich/find-email | Trouver l’email professionnel |
| POST | /enrich/reverse-email | Identifier un contact par email |
| POST | /enrich/firmographic | Données firmographiques |
| POST | /enrich/financial | Données financières |
| POST | /enrich/french-sirene | Données SIRENE |
| POST | /enrich/tech-stack | Stack technique |
| POST | /enrich/website-traffic | Trafic web |
| POST | /enrich/homepage-content | Contenu page d’accueil |
| POST | /enrich/company-jobs | Offres d’emploi actives |
| POST | /enrich/profile-posts | Publications LinkedIn profil |
| POST | /enrich/company-posts | Publications LinkedIn entreprise |
POST /enrich/contact
Enrichit un contact à partir de son nom et du domaine de son entreprise. Retourne les informations professionnelles disponibles : poste, département, ancienneté, profil LinkedIn et coordonnées vérifiées.
{
"first_name": "Marie",
"last_name": "Dupont",
"company_domain": "exemple.fr"
}POST /enrich/find-email
Trouve l’adresse email professionnelle d’un contact à partir de son nom et de son entreprise. L’API vérifie la validité de l’email avant de le retourner. Le champ confidence dans la réponse indique le niveau de certitude (élevé, moyen ou faible).
POST /enrich/reverse-email
Opération inverse : à partir d’une adresse email, identifie le contact et retourne ses informations professionnelles. Utile pour qualifier des leads entrants dont vous ne connaissez que l’email.
POST /enrich/firmographic
Retourne les données firmographiques d’une entreprise : secteur d’activité, taille, chiffre d’affaires estimé, localisation, date de création, forme juridique et structure capitalistique. Accepte un domaine, un nom d’entreprise ou un identifiant SIREN.
POST /enrich/financial
Fournit les données financières publiques d’une entreprise : dernier chiffre d’affaires déclaré, résultat net, effectif, bilans disponibles. Particulièrement complet pour les entreprises françaises grâce aux données légales.
POST /enrich/french-sirene
Requête spécifique aux entreprises immatriculées en France. Retourne les données du répertoire SIRENE : numéro SIREN, SIRET, code NAF, adresse du siège, date de création et statut administratif.
POST /enrich/tech-stack
Analyse la stack technique d’une entreprise à partir de son domaine. Détecte les technologies utilisées : CMS, outils d’analytics, CRM, plateformes publicitaires, frameworks et hébergement. Idéal pour les éditeurs de logiciels qui ciblent des prospects selon leur écosystème technologique.
POST /enrich/website-traffic
Estime le trafic web d’un domaine : visiteurs mensuels, pages vues, durée moyenne de session, sources de trafic et répartition géographique. Ces données permettent d’évaluer la maturité digitale d’un prospect.
POST /enrich/homepage-content
Récupère et analyse le contenu de la page d’accueil d’un site web. Retourne les textes clés, les mots-clés identifiés et un résumé de l’activité. Utile pour personnaliser vos approches commerciales.
POST /enrich/company-jobs
Liste les offres d’emploi actuellement publiées par une entreprise. Le nombre et le type de postes ouverts sont des signaux puissants : une entreprise qui recrute des commerciaux est en phase de croissance, une entreprise qui recrute un CTO envisage peut-être un changement technologique.
POST /enrich/profile-posts
Récupère les publications récentes d’un profil LinkedIn. Permet de comprendre les sujets d’intérêt de votre prospect et de personnaliser votre prise de contact avec des références précises à ses publications.
POST /enrich/company-posts
Récupère les publications récentes d’une page entreprise LinkedIn. Offre une vue sur la communication officielle, les lancements de produits, les événements et la culture d’entreprise.
Endpoints Webhooks
Les webhooks vous permettent de recevoir les signaux en temps réel, sans interroger l’API en permanence. Quand un signal correspond à l’une de vos configurations, Rodz envoie automatiquement une requête POST vers l’URL que vous avez enregistrée.
Pour un guide complet sur la mise en place des webhooks, consultez l’article Recevoir les signaux en temps réel avec les webhooks.
| Méthode | Endpoint | Description |
|---|---|---|
| POST | /webhooks | Enregistrer un webhook |
| GET | /webhooks | Lister vos webhooks |
| DELETE | /webhooks/:id | Supprimer un webhook |
| POST | /webhooks/:id/test | Tester un webhook |
POST /webhooks
Enregistre un nouveau webhook. Le corps de la requête doit contenir l’URL de destination et, optionnellement, un secret de vérification et les types d’événements à écouter.
{
"url": "https://votre-serveur.com/rodz-webhook",
"secret": "votre_secret_de_verification",
"events": ["signal.new", "signal.updated"]
}Rodz signe chaque requête avec votre secret via un en-tête X-Rodz-Signature. Vérifiez systématiquement cette signature côté serveur pour garantir l’authenticité des appels.
GET /webhooks
Retourne la liste de vos webhooks enregistrés avec leur statut (actif, inactif, en erreur), la date du dernier appel réussi et le nombre d’appels échoués consécutifs.
DELETE /webhooks/:id
Supprime un webhook. Les appels vers cette URL cessent immédiatement. Si vous souhaitez temporairement désactiver un webhook sans le supprimer, utilisez plutôt une mise à jour de statut.
POST /webhooks/:id/test
Envoie une requête de test vers l’URL de votre webhook avec un payload d’exemple. Utilisez cet endpoint pour valider votre intégration avant de passer en production. La réponse inclut le code HTTP retourné par votre serveur et le temps de réponse.
Limites de débit (Rate Limiting)
L’API Rodz applique des limites de débit pour garantir la stabilité du service pour tous les utilisateurs.
Limites par défaut
- 100 requêtes par minute par clé API
- Les limites s’appliquent par clé API, pas par adresse IP
- Les endpoints d’enrichissement consomment 1 crédit par appel en plus du quota de requêtes
En-têtes de suivi
Chaque réponse de l’API inclut trois en-têtes pour suivre votre consommation :
| En-tête | Description |
|---|---|
X-RateLimit-Limit | Nombre maximum de requêtes autorisées par minute |
X-RateLimit-Remaining | Nombre de requêtes restantes dans la fenêtre actuelle |
X-RateLimit-Reset | Timestamp Unix indiquant quand le compteur sera réinitialisé |
Réponse 429 : Too Many Requests
Quand vous dépassez la limite, l’API retourne un code 429 avec un corps JSON indiquant le délai d’attente :
{
"success": false,
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Trop de requêtes. Réessayez dans 32 secondes.",
"retry_after": 32
}
}Bonnes pratiques
Pour éviter d’atteindre les limites de débit, adoptez ces stratégies :
- Implémentez un backoff exponentiel. En cas de réponse 429, attendez 1 seconde avant le premier retry, puis 2 secondes, puis 4, et ainsi de suite. Ne dépassez pas 5 tentatives.
- Utilisez les webhooks plutôt que le polling. Au lieu d’interroger
/signals/feedtoutes les minutes, enregistrez un webhook qui recevra les signaux en temps réel. Cela réduit considérablement le nombre de requêtes. - Mettez en cache les données statiques. Les réponses de
/signals/typeschangent rarement. Mettez-les en cache côté client pendant 24 heures. - Regroupez vos requêtes d’enrichissement. Plutôt que d’enrichir les contacts un par un au fil de la journée, traitez-les par lots à intervalles réguliers.
- Surveillez les en-têtes de débit. Intégrez la lecture de
X-RateLimit-Remainingdans votre code pour ralentir proactivement avant d’atteindre la limite.
Codes d’erreur
L’API utilise les codes HTTP standards. Voici la liste complète des codes que vous pouvez rencontrer et l’action recommandée pour chacun :
| Code | Signification | Action recommandée |
|---|---|---|
| 200 | Succès | Traiter la réponse normalement |
| 201 | Créé avec succès | La ressource a été créée, traiter la réponse |
| 400 | Requête invalide | Vérifier le corps de la requête et les paramètres |
| 401 | Non authentifié | Vérifier votre clé API dans l’en-tête Authorization |
| 403 | Accès refusé | Vérifier vos permissions et votre plan |
| 404 | Ressource non trouvée | Vérifier l’URL et l’identifiant de la ressource |
| 429 | Trop de requêtes | Attendre le délai indiqué dans retry_after et réessayer |
| 500 | Erreur serveur | Réessayer après quelques secondes, contacter le support si persistant |
Structure des erreurs
Toutes les réponses d’erreur suivent le même format JSON :
{
"success": false,
"error": {
"code": "INVALID_PARAMETER",
"message": "Le champ 'signal_type' est requis.",
"details": {
"field": "signal_type",
"constraint": "required"
}
}
}Le champ code contient un identifiant machine lisible que vous pouvez utiliser dans votre logique de gestion d’erreurs. Le champ message fournit une explication en langage naturel. Le champ details, optionnel, apporte des précisions supplémentaires selon le type d’erreur.
Codes d’erreur applicatifs
En plus des codes HTTP, l’API retourne des codes d’erreur spécifiques dans le champ error.code :
| Code applicatif | Description |
|---|---|
INVALID_PARAMETER | Un paramètre de la requête est invalide |
MISSING_PARAMETER | Un paramètre requis est absent |
RATE_LIMIT_EXCEEDED | La limite de débit est dépassée |
INSUFFICIENT_CREDITS | Crédits d’enrichissement insuffisants |
CONFIGURATION_LIMIT | Nombre maximum de configurations atteint |
WEBHOOK_UNREACHABLE | L’URL du webhook ne répond pas |
RESOURCE_NOT_FOUND | La ressource demandée n’existe pas |
Format des réponses
Toutes les réponses de l’API sont au format JSON et suivent une structure cohérente.
Réponse simple (succès)
{
"success": true,
"data": {
"id": "sig_abc123",
"type": "fundraising",
"company": {
"name": "TechStartup SAS",
"domain": "techstartup.fr",
"siren": "123456789"
},
"details": {
"amount": 5000000,
"currency": "EUR",
"round": "Series A",
"investors": ["Venture Capital Fund"]
},
"detected_at": "2026-03-05T09:30:00Z"
}
}Réponse avec pagination
Les endpoints qui retournent des listes utilisent la pagination par curseur (voir section suivante). La structure inclut un objet pagination :
{
"success": true,
"data": [
{
"id": "sig_abc123",
"type": "fundraising",
"company": { "name": "TechStartup SAS" },
"detected_at": "2026-03-05T09:30:00Z"
},
{
"id": "sig_def456",
"type": "new_hiring",
"company": { "name": "ScaleUp Inc" },
"detected_at": "2026-03-05T08:15:00Z"
}
],
"pagination": {
"cursor": "eyJpZCI6InNpZ19kZWY0NTYifQ==",
"has_more": true,
"total": 847,
"limit": 50
}
}Champs communs
Voici les champs présents dans la plupart des réponses :
| Champ | Type | Description |
|---|---|---|
success | boolean | Indique si la requête a réussi |
data | object ou array | Les données demandées |
error | object | Présent uniquement en cas d’erreur |
pagination | object | Présent pour les endpoints paginés |
Pagination
L’API Rodz utilise la pagination par curseur (cursor-based pagination). Cette approche est plus fiable que la pagination par offset, car elle garantit qu’aucun élément ne sera manqué ou dupliqué si des données sont ajoutées entre deux requêtes.
Paramètres de pagination
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
cursor | string | (vide) | Curseur opaque retourné par la requête précédente |
limit | integer | 50 | Nombre de résultats par page (min 1, max 200) |
Fonctionnement
- Première requête : appelez l’endpoint sans paramètre
cursor. Vous recevez les premiers résultats et un curseur danspagination.cursor. - Requêtes suivantes : passez le curseur reçu comme paramètre pour obtenir la page suivante.
- Dernière page : quand
pagination.has_morevautfalse, vous avez récupéré tous les résultats.
Exemple de parcours complet
# Première page
curl -X GET "https://api.rodz.io/v1/signals/feed?limit=100" \
-H "Authorization: Bearer VOTRE_CLE_API"
# Pages suivantes (utiliser le curseur reçu)
curl -X GET "https://api.rodz.io/v1/signals/feed?limit=100&cursor=eyJpZCI6InNpZ19kZWY0NTYifQ==" \
-H "Authorization: Bearer VOTRE_CLE_API"Bonnes pratiques de pagination
- Utilisez un
limitadapté à votre cas d’usage. Pour un traitement par lots, 200 réduit le nombre d’appels. Pour un affichage temps réel, 50 offre un bon compromis. - Ne stockez pas les curseurs indéfiniment. Ils peuvent expirer après 24 heures d’inactivité.
- Ne modifiez pas les curseurs. Ce sont des chaînes opaques encodées en base64. Toute modification les invalidera.
- Si vous recevez une erreur
INVALID_CURSOR, recommencez la pagination depuis le début sans curseur.
Questions fréquentes
Quel format de date utiliser dans les paramètres ?
L’API attend des dates au format ISO 8601 : 2026-03-05T09:30:00Z. Le fuseau horaire doit être UTC (suffixe Z). Si vous omettez le fuseau, l’API interprète la date en UTC par défaut.
Comment tester l’API sans consommer de crédits ?
L’endpoint /webhooks/:id/test envoie des données de test sans consommer de crédits. Pour les endpoints d’enrichissement, utilisez l’environnement sandbox si votre plan le permet. Contactez le support pour activer l’accès sandbox.
Les curseurs de pagination expirent-ils ?
Oui. Un curseur devient invalide après 24 heures sans utilisation. Si vous traitez de gros volumes de données, assurez-vous de terminer votre parcours de pagination dans ce délai. En cas de curseur expiré, l’API retourne une erreur INVALID_CURSOR et vous devez recommencer depuis le début.
Puis-je augmenter ma limite de débit ?
Oui. La limite par défaut de 100 requêtes par minute convient à la plupart des usages. Si votre intégration nécessite un débit plus élevé, contactez l’équipe Rodz pour discuter d’un plan adapté. Les limites personnalisées peuvent monter jusqu’à 1 000 requêtes par minute selon votre cas d’usage.
Comment gérer les erreurs 500 ?
Les erreurs 500 sont rares et indiquent un problème côté serveur. Implémentez un retry avec backoff exponentiel (attendre 1 s, puis 2 s, puis 4 s). Si l’erreur persiste après 3 tentatives, contactez le support Rodz en incluant le request_id présent dans les en-têtes de la réponse. Ce champ permet à l’équipe technique d’identifier rapidement la cause.
Quelle est la différence entre /enrich/contact et /enrich/find-email ?
L’endpoint /enrich/contact retourne un profil complet (poste, département, profil LinkedIn, coordonnées) à partir d’un nom et d’un domaine. L’endpoint /enrich/find-email se concentre uniquement sur la recherche et la vérification de l’email professionnel. Si vous n’avez besoin que de l’email, utilisez /enrich/find-email pour une réponse plus rapide et une consommation de crédits optimisée.
Les données d’enrichissement sont-elles mises en cache ?
Oui. Les données d’enrichissement sont mises en cache pendant 7 jours côté serveur. Une requête sur des données déjà en cache retourne les résultats instantanément et ne consomme pas de crédit supplémentaire. Pour forcer un rafraîchissement, ajoutez le paramètre force_refresh=true à votre requête (cela consomme un crédit).
Comment vérifier la signature d’un webhook ?
Chaque appel webhook inclut un en-tête X-Rodz-Signature contenant un hash HMAC-SHA256 du corps de la requête, calculé avec votre secret. Côté serveur, recalculez le hash avec le même secret et comparez-le à la valeur de l’en-tête. Si les deux valeurs correspondent, l’appel est authentique. Le guide webhooks détaille l’implémentation dans plusieurs langages.
Pour aller plus loin
Cette page de référence couvre l’ensemble des endpoints, des limites et des conventions de l’API Rodz. Pour une prise en main progressive, suivez les guides techniques dans l’ordre :
- Guide de démarrage : authentification et première requête
- Configurer votre premier signal d’affaires via l’API
- Recevoir les signaux en temps réel avec les webhooks
Pour explorer l’API de manière interactive avec des exemples exécutables, consultez la documentation API complète.
Vous avez des questions sur l’intégration ou un cas d’usage spécifique ? Réservez un créneau avec l’équipe Rodz pour en discuter.