Passer au contenu principal

API d'Enrichissement Zeliq

Qu'est-ce que l'API d'Enrichissement Zeliq ?

Mis à jour aujourd’hui

L'API d'Enrichissement Zeliq vous permet de trouver des emails et numéros de téléphone vérifiés de manière programmatique, sans utiliser le tableau de bord Zeliq. Elle est conçue pour les équipes qui souhaitent intégrer le moteur d'enrichissement de Zeliq dans leurs propres outils, workflows ou applications (n8n, Make, Clay, CRM personnalisés, etc.).

L'API est asynchrone : vous envoyez une requête avec une URL de callback, et Zeliq publie les résultats sur cette URL une fois l'enrichissement terminé.

L'API est asynchrone : vous envoyez une requête avec une URL de callback, et Zeliq publie les résultats sur cette URL une fois l'enrichissement terminé.

Pour commencer

Où trouver la clé API?

Rendez-vous dans Paramètres > API dans votre espace Zeliq. Vous devez avoir un accès administrateur pour voir la clé. Votre clé API commence par sk- et est unique à votre organisation.

Comment m'authentifier?

Ajoutez votre clé API dans l'en-tête x-api-key de chaque requête :

x-api-key: sk-votre-clé-api-ici

⚠️ N'utilisez pas l'authentification par token Bearer. La seule méthode supportée est l'en-tête x-api-key.

Endpoints disponibles

1.Vérifier votre solde de crédits

GET https://app.zeliq.com/api/credits/balance

Réponse :

Credit Balance4500

Cet endpoint n'est pas soumis aux limites de taux.

2.Enrichir une adresse email 

POST https://app.zeliq.com/api/contact/enrich/email

Corps de la requête — Option A (avec URL LinkedIn) :

{   "linkedin_url": "<https://linkedin.com/in/johndoe>",   "callbackUrl": "<https://your-server.com/webhook>" }

Corps de la requête — Option B (sans URL LinkedIn) :

{   "first_name": "John",   "last_name": "Doe",   "company": "Acme Inc",   "callbackUrl": "<https://your-server.com/webhook>" }

  • callbackUrl — toujours obligatoire, doit être une URL HTTP ou HTTPS valide

  • Soit linkedin_url, soit la combinaison first_name + last_name + (company ou domain)

Champs optionnels :

  • domain — le domaine du site web de l'entreprise (alternative à company)

Coût :

  • 1 crédit par enrichissement (0 crédit sur les plans Advanced et Enterprise)

  • Les crédits sont remboursés si aucun email n'est trouvé

3. Enrichir un numéro de téléphone

nrich/phone

Corps de la requête :

{   "linkedin_url": "<https://linkedin.com/in/johndoe>",   "callbackUrl": "<https://your-server.com/webhook>" }

ou :

{   "email": "[email protected]",   "callbackUrl": "<https://your-server.com/webhook>" }

Champs obligatoires :

  • callbackUrl — toujours obligatoire

  • Soit linkedin_url, soit email

Coût :

  • 10 crédits par enrichissement

  • Les crédits sont remboursés si aucun numéro n'est trouvé

Comment fonctionne le flux asynchrone ?

  1. Vous envoyez votre requête d'enrichissement avec un callbackUrl

  2. Vous recevez une réponse immédiate (HTTP 202) avec un jobId

  3. Zeliq traite l'enrichissement via 10+ fournisseurs de données (waterfall)

  4. Zeliq envoie le résultat à votre callbackUrl lorsqu'il est prêt

Réponse immédiate reçue (HTTP 202) :

{   "status": 202,   "message": "Request accepted, results will be sent to the callback URL",   "jobId": "a1b2c3d4-e5f6-..." }

💡 Conseil pro : Incluez votre propre identifiant dans l'URL de callback (ex. ?contactId=123) pour associer les résultats à vos enregistrements.

Payloads du callback

Callback d'enrichissement email

Envoyé à votre callbackUrl lorsque l'enrichissement est terminé :

{   "credit_used": 1,   "contact": {     "first_name": "John",     "last_name": "Doe",     "domain": "acme.com",     "linkedin_url": "<https://linkedin.com/in/johndoe>",     "most_probable_email": "[email protected]",     "most_probable_email_status": "valid",     "emails": [       { "email": "[email protected]", "status": "valid" },       { "email": "[email protected]", "status": "catch-all" }     ]   } }

  • most_probable_email — le meilleur email trouvé

  • most_probable_email_status — résultat de vérification (valid, catch-all, invalid, etc.)

  • emails — tous les emails trouvés avec leur statut de vérification

  • credit_used — crédits réellement débités (0 si rien n'est trouvé)

Callback d'enrichissement téléphone 

{   "credit_used": 10,   "contact": {     "linkedin_url": "<https://linkedin.com/in/johndoe>",     "email": "[email protected]",     "most_probable_phone": "+33612345678",     "phones": [       { "phone": "+33612345678" },       { "phone": "+33698765432" }     ]   } }

  • most_probable_phone — le meilleur numéro trouvé

  • phones — tous les numéros de téléphone trouvés

  • credit_used — crédits réellement débités (0 si rien n'est trouvé)

Limites de Taux

Plan

Per minute

Per hour

Per day

Free

50

200

600

Starter

200

400

2,000

Essential / Advanced / Enterprise

600

2,000

6,000

Les limites de taux dépendent de votre plan Zeliq :

L'endpoint de solde de crédits (GET /api/credits/balance) est exempté des limites de taux.

Codes d'erreur et dépannage

400 — Mauvais requête

Signification : Votre requête est incomplète ou contient des données invalides.

Messages courants :

  • "linkedin_url or email is required" — pour l'enrichissement téléphone, vous devez fournir au moins l'un de ces champs

  • "Either linkedin_url OR (first_name, last_name, and company or domain) are required" — pour l'enrichissement email

  • Erreur de validation sur callbackUrl — vérifiez que c'est une URL valide commençant par http:// ou https://

Que faire : Vérifiez les champs obligatoires pour l'endpoint appelé. Assurez-vous que callbackUrl est présent et valide.

401 — Non autorisé

Signification : L'authentification a échoué.

Messages courants :

  • "API key is required" — vous avez oublié l'en-tête x-api-key

  • "Invalid API key" — la clé n'existe pas ou a été régénérée

Que faire :

  • Envoyez la clé dans l'en-tête x-api-key (pas en Bearer token, pas en paramètre de requête)

  • Vérifiez votre clé dans Paramètres > API

  • Si vous avez récemment régénéré votre clé, mettez-la à jour dans votre intégration

402 — Paiement requis

Signification : Votre organisation n'a plus de crédits.

Message : "No Credit Remaining"

Que faire : Achetez des crédits supplémentaires ou passez à un plan supérieur dans Paramètres > Facturation.

423 — Verrouillé

Signification : Votre compte utilisateur a été bloqué.

Message : "User is blocked"

Que faire : Contactez le support à [email protected].

429 — Trop de requêtes

Signification : Vous avez dépassé la limite de taux de votre plan.

Que faire :

  • L'objet limits vous indique les limites de votre plan actuel

  • Attendez un moment avant de réessayer

  • Si vous atteignez régulièrement les limites, envisagez de passer à un plan supérieur

  • Implémentez un backoff exponentiel dans votre intégration

FAQ

Puis-je utiliser l'API sans URL de callback ?

Non. Le callbackUrl est obligatoire pour toutes les requêtes d'enrichissement. L'API est entièrement asynchrone.

Combien de temps dure un enrichissement ?

La plupart des enrichissements se terminent en quelques secondes à quelques minutes. Dans de rares cas, cela peut prendre plus longtemps selon la disponibilité des fournisseurs.

Suis-je facturé si aucune donnée n'est trouvée ?

Non. Les crédits ne sont débités que pour les enrichissements réussis. Si aucun email ou numéro n'est trouvé, credit_used sera 0 dans le callback.

Puis-je enrichir email et téléphone en un seul appel ?

Non. Les enrichissements email et téléphone sont des endpoints séparés. Vous devez faire deux appels API.

Le nom de champ callback_url fonctionne-t-il aussi ?

Oui. callbackUrl et callback_url sont tous les deux acceptés dans le corps de la requête.

Quels statuts d'email puis-je recevoir ?

Le champ most_probable_email_status peut retourner : valid, catch-all, invalid, unknown.

Existe-t-il un mode synchrone ?

Non. L'API fonctionne uniquement en mode asynchrone avec une URL de callback.

Puis-je suivre l'origine de mes appels API ?

Oui. Ajoutez un en-tête x-request-origin (max 50 caractères) pour taguer vos requêtes à des fins de suivi.

Quels plans ont accès à l'API ?

Tous les plans (Free, Starter, Essential, Advanced, Enterprise) ont accès à l'API. La différence réside dans les limites de taux et les coûts en crédits.

Plusieurs utilisateurs peuvent-ils partager la même clé API ?

La clé API est liée à l'organisation, pas aux utilisateurs individuels. Tous les membres partagent la même clé et les mêmes limites de taux.

Carte de référence rapide

Email enrichment

Phone enrichment

Endpoint

POST /api/contact/enrich/email

POST /api/contact/enrich/phone

Required input

linkedin_url OR (first_name • last_name • company/domain)

linkedin_url OR email

Callback URL

Required

Required

Credit cost

1 credit (0 on Advanced/Enterprise)

10 credits

Refund if not found

Yes

Yes

Auth

x-api-key header

x-api-key header

Articles connexes
Enrichir les coordonnées d'un prospect
🔌 Comment utiliser l'enrichissement ZELIQ sur Clay ?
Configurer l'enrichissement Zeliq via N8N
Avez-vous trouvé la réponse à votre question ?