API client

Commencer

Créez une clé de test dans Clés API, conservez-la sur votre serveur et définissez FAIRVALID_API_KEY et FAIRVALID_BASE_URL. Les clés de test fonctionnent avec les adresses réservées @example.com. Elles n’appellent aucun fournisseur et n’utilisent aucun crédit.

curl -X POST "$FAIRVALID_BASE_URL/api/v1/jobs" \
  -H "Authorization: Bearer $FAIRVALID_API_KEY" \
  -H "Idempotency-Key: my-import-2026-10-05" \
  -H "Content-Type: application/json" \
  -d '{"emails":["deliverable@example.com","pending@example.com"]}'

En production, créez une clé Live avec la portée submit et utilisez /api/v1/jobs ou /api/v1/verifications. Ajoutez la portée read pour lire l’état et les résultats des tâches.

Une nouvelle tâche renvoie HTTP 202 et un UUID job_id. Une nouvelle tentative identique renvoie HTTP 200 avec la même tâche. Les réponses incluent version: v1, brand: FairValid et des en-têtes no-store.

Clés et plafonds de dépenses

Transmettez Authorization: Bearer fv_live_… ou Bearer fv_test_… depuis un serveur. Les secrets complets ne s’affichent qu’une seule fois. Les clés de production peuvent avoir les portées submit, read et balance. Une clé révoquée bloque toute nouvelle requête. Les clés de test accèdent à leurs propres tâches simulées.

Le plafond à vie d’une clé de production comptabilise les crédits déjà débités ainsi que les crédits réservés pour les identités uniques acceptées. Il ne peut pas ajouter de crédits à l’espace de travail. Une nouvelle requête dépassant le plafond renvoie HTTP 402 key_cap_reached sans créer de tâche ni de réservation. Abaisser le plafond bloque les nouvelles tâches ; les tâches acceptées se poursuivent.

Les tâches en production utilisent la file de vérification et le solde de crédits de votre espace de travail. Les portées et plafonds des clés, l’accès à l’espace de travail et les limites de traitement s’appliquent toujours. Les crédits de l’espace de travail sont réservés à mesure que les vérifications sont admises au traitement ; les résultats suivent les mêmes règles de débit et de restitution que dans le tableau de bord.

Pendant une pause opérationnelle, une nouvelle soumission en production peut renvoyer HTTP 503 live_verification_unavailable sans réserver de crédits. Réessayez plus tard avec la même Idempotency-Key.

Tâches et résultats

curl "$FAIRVALID_BASE_URL/api/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $FAIRVALID_API_KEY"
curl "$FAIRVALID_BASE_URL/api/v1/jobs/$JOB_ID/results" \
  -H "Authorization: Bearer $FAIRVALID_API_KEY"

Transmettez next_cursor comme paramètre de requête cursor. Il reprend le filtre et la recherche d’origine. Les filtres sont all, valid, invalid, catch_all, unknown, still_checking et not_checked. Les états des résultats et des crédits en production correspondent à l’instantané du tableau de bord. Le statut d’une tâche peut être queued, running, paused, canceling, canceled ou completed. Les tâches de test renvoient des états déterministes : completed, pending, failed ou cancelled.

Erreurs et nouvelles tentatives sécurisées

Envoyez un Idempotency-Key de 8 à 128 caractères autorisés (lettres, chiffres, points, deux-points, traits de soulignement ou traits d’union) avec chaque soumission de tâche et chaque soumission en direct d’une adresse unique. En cas de réponse incertaine, réessayez avec la même clé API, la même clé d’idempotence et le même corps normalisé. La relecture est limitée à la clé API ; remplacer cet identifiant et soumettre à nouveau peut créer une autre exécution. Réutiliser la clé d’idempotence avec un corps modifié renvoie HTTP 409 idempotency_conflict. N’utilisez une nouvelle clé que si vous souhaitez lancer une nouvelle exécution, susceptible de débiter des crédits.

Le code HTTP 401 signifie que la clé est manquante, révoquée ou ne dispose pas de la portée requise. Le code HTTP 422 concerne les adresses invalides ou les limites de liste. Les tâches groupées de test renvoient HTTP 429 au-delà de 20 nouvelles tâches par espace de travail et par heure, ou de 100 sur 30 jours ; les nouvelles tentatives identiques renvoient toujours la tâche d’origine. Le code HTTP 503 signifie que la requête est temporairement indisponible ; un code 503 reçu après une soumission incertaine ne prouve pas qu’aucune tâche n’a été créée : réessayez donc avec la même clé d’idempotence. Les erreurs contiennent un code, un message et un identifiant de requête.

Sandbox gratuite

Les clés de test n’acceptent que ces adresses : deliverable@example.com, undeliverable@example.com, risky@example.com, unknown@example.com, pending@example.com et error@example.com. Elles simulent des résultats valide, invalide, catch-all, inconnu, en attente et indisponible. Les tâches de test groupées prennent en charge le statut, les résultats, l’annulation et la relecture sans affecter la vérification réelle ni le registre de crédits.

Les tâches groupées en sandbox et leurs enregistrements de relecture sont conservés pendant 30 jours. Passé ce délai, utilisez une nouvelle clé d’idempotence pour un nouveau test.

Le simulateur de clé de test /api/v1/verifications d’origine utilise son ancienne version de réponse 2026-10-01 et des champs en camelCase. Utilisez /api/v1/jobs pour le simulateur en masse versionné.

Webhooks signés

Les rôles Propriétaire et Gestionnaire configurent des points de terminaison HTTPS pour job.completed et job.canceled. Un ping de test utilise test.ping. Les charges utiles des tâches contiennent un identifiant d’événement stable, l’identifiant de la tâche, son état, un résumé sans adresses, le nombre de crédits débités et restitués, ainsi qu’une URL de résultats. Elles n’incluent jamais d’adresses e-mail ni de données des fournisseurs.

Lisez FairValid-Webhook-Id, FairValid-Webhook-Timestamp et FairValid-Webhook-Signature. La signature est fv1= suivi de l'empreinte HMAC-SHA256 hexadécimale en minuscules calculée sur les octets bruts de fv1\n{event ID}\n{Unix timestamp}\nsuivis immédiatement du corps JSON brut. Utilisez une comparaison à temps constant. Rejetez les horodatages s'écartant de plus de cinq minutes de votre horloge et dédupliquez par ID d'événement dans un stockage persistant.

Renvoyez un code 2xx dans un délai de 10 secondes. Les livraisons échouées ou incertaines sont relancées jusqu’à huit fois avec le même identifiant d’événement ; consultez l’historique sur 30 jours ou relancez manuellement la livraison. Les redirections et les destinations privées sont refusées. Après la rotation, les nouvelles tentatives utilisent le nouveau secret. Conservez l’ancien secret pendant 24 heures pour vérifier les signatures des tentatives en cours.

Exemples exécutables

Le dépôt inclut packages/contracts/examples/job.mjset packages/contracts/examples/webhook-receiver.mjs. Exécutez l’exemple de tâche avec Node 22 et une clé de test. Le récepteur vérifie les octets exacts du corps brut ainsi que les secrets actuel et précédent pendant la rotation. Placez-le derrière HTTPS et remplacez son ensemble d’ID d’événements en mémoire par un stockage atomique durable avant toute utilisation en production.

FAIRVALID_API_KEY=... FAIRVALID_BASE_URL=https://YOUR_FAIRVALID_HOST \
  node packages/contracts/examples/job.mjs