Développeurs
Une requête à l’inscription, une décision claire
Appelez l’API depuis votre serveur au moment de l’inscription : vous savez s’il faut bloquer l’adresse et s’il faut accorder l’offre promo. Réponse en quelques millisecondes.
curl -X POST https://api.useksar.com/v1/check-email \
-H "x-api-key: $KSAR_API_KEY" \
-H "content-type: application/json" \
-d '{"email":"[email protected]","event":"signup","offer":"welcome_discount"}'200 OK
{
"block": false,
"risk_score": 6,
"duplicate": { "status": "exact", "count": 2 },
"offer": { "decision": "deny", "reasons": ["duplicate_exact"] }
}Démarrage rapide
En production en trois étapes
- 1
Créez un compte
Inscription gratuite, sans carte bancaire. Votre clé API s’affiche une seule fois : copiez-la.
- 2
Gardez la clé côté serveur
Placez-la dans une variable d’environnement (KSAR_API_KEY). Elle ne doit jamais apparaître dans le navigateur ni dans une application mobile.
- 3
Faites le premier appel
Envoyez l’adresse avec event « signup » au moment de l’inscription, puis appliquez block et offer.decision. Le tableau de bord propose un bouton « Tester maintenant ».
Réponse
Les champs à utiliser
La réponse complète est décrite dans la référence ; ces champs suffisent pour décider.
| Champ | Valeurs | Signification |
|---|---|---|
| block | boolean | true : refusez l’inscription (adresse jetable, domaine sans e-mail…). |
| risk_score | 0–100 | Score de risque de l’adresse ; block vaut true au-delà de votre seuil. |
| reasons | string[] | Raisons détectées (disposable_domain, no_mx, duplicate_exact…). |
| duplicate.status | none · exact · series | La même personne (ou une série d’adresses proches) s’est déjà inscrite. |
| offer.decision | grant · defer · deny | Accorder l’offre promo, la mettre en attente (accordée plus tard) ou la refuser. |
| mode | enforce · shadow | shadow : mode test, rien n’est bloqué ; les décisions réelles sont dans shadow. |
| degraded | boolean | true si une dépendance interne était indisponible : réponse avec les signaux disponibles. |
| not_included | string[] | Fonctions non incluses dans votre offre (doublons, décision sur l’offre promo…). |
Bonnes pratiques
Une intégration qui ne casse jamais votre formulaire
Uniquement depuis votre serveur
La clé donne accès à votre compte : jamais d’appel depuis le navigateur ou une application mobile.
Délai court, puis laisser passer
Fixez un délai de 2 secondes. En cas d’erreur, de délai dépassé ou de réponse inattendue, acceptez l’inscription : votre formulaire ne doit jamais tomber à cause de l’API.
Quota atteint (429)
quota_exceeded : laissez passer les inscriptions jusqu’au renouvellement (resets_at) ou passez à une offre supérieure ; vous êtes prévenu par e-mail à 80 % et 100 %. rate_limit_exceeded : respectez Retry-After.
Inscription ou simple vérification
event « signup » enregistre l’inscription (doublons, rapports) ; event « check » analyse sans rien enregistrer. Ajoutez external_id pour retrouver vos comptes.
Offre promo en attente
Avec offer.decision « defer », accordez l’offre promo plus tard : envoyez les événements (adresse confirmée, premier achat) à /v1/signups/{signup_id}/events.
Exemple : appel avec délai et repli
// Appelé par votre serveur à l’inscription.
async function checkSignup(email) {
try {
const res = await fetch('https://api.useksar.com/v1/check-email', {
method: 'POST',
headers: { 'x-api-key': process.env.KSAR_API_KEY, 'content-type': 'application/json' },
body: JSON.stringify({ email, event: 'signup', offer: 'welcome_discount' }),
signal: AbortSignal.timeout(2000),
});
if (!res.ok) return { block: false, offer: 'grant' }; // 429, 5xx : laisser passer
const data = await res.json();
return { block: data.block, offer: data.offer.decision };
} catch {
return { block: false, offer: 'grant' }; // délai dépassé ou réseau : laisser passer
}
}Erreurs
Codes d’erreur
| HTTP | error | Que faire |
|---|---|---|
| 400 | invalid_email | Adresse syntaxiquement invalide : demandez de la corriger. |
| 401 | invalid_api_key | Clé absente, révoquée ou invalide : vérifiez la variable d’environnement. |
| 403 | insufficient_scope | La clé n’a pas le droit nécessaire (check ou admin). |
| 403 | plan_upgrade_required | Fonction non incluse dans votre offre (rapport, audit CSV). |
| 403 | account_suspended | Compte suspendu : contactez-nous ; laissez passer les inscriptions. |
| 429 | rate_limit_exceeded | Trop de requêtes par minute : respectez Retry-After. |
| 429 | quota_exceeded | Quota du mois atteint : laissez passer les inscriptions. |
| 503 | service_unavailable | Service momentanément indisponible : laissez passer les inscriptions. |
Bac à sable
Essayez toutes les fonctions sans compte
Un client fictif rien qu’à vous pendant 24 heures : inscriptions, règles, rapport en euros, audit d’un fichier et effacement RGPD.