API Reference v1.0

DOC API

Intégrez la vérification spam directement dans vos centres d'appels, CRM et dialers. API REST simple, rapide et fiable.

Authentification

Toutes les requêtes nécessitent un token Bearer. Récupérez votre token dans votre dashboard > API.

HTTP HEADER REQUIS

Authorization: Bearer spk_live_xxxxxxxxxxxx

Récupérer votre token

Connectez-vous à votre dashboard
Allez dans "API" dans le menu
Copiez votre token ou régénérez-en un nouveau

Sécurité

• Ne partagez jamais votre token
• Régénérez-le si compromis
• Utilisez des variables d'environnement

POST/auth/regenerate-token

Régénère votre token API. L'ancien token devient immédiatement invalide.

{
  "success": true,
  "data": {
    "apiToken": "spk_live_new_token_here"
  }
}

GET

/check/{phone}

0.70€ / vérification

Analyse instantanée d'un numéro de téléphone. Retourne le score spam, le type de spam, l'opérateur et la localisation.

Paramètres URL

Paramètre	Type	Requis	Description
phone	string	Oui	Numéro au format international (ex: +33612345678)

curl -X GET "https://num.huhu.fr/api/check/+33612345678" \
  -H "Authorization: Bearer spk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Réponse JSON

{
  "success": true,
  "data": {
    "phoneNumber": "+33612345678",
    "isSpam": true,
    "spamScore": 85,
    "spamType": "Telemarketing",
    "carrier": "Orange",
    "location": "France",
    "lineType": "mobile",
    "checkedAt": "2026-01-24T10:30:00Z"
  },
  "balance": 14.30
}

Champs de la réponse

phoneNumberstringNuméro analysé au format international

isSpambooleantrue si le numéro est identifié comme spam

spamScorenumberScore de 0 à 100 (0 = sûr, 100 = spam certain)

spamTypestringType de spam: Telemarketing, Scam, Robocall, Survey, Unknown

carrierstringOpérateur téléphonique (Orange, SFR, Free, Bouygues...)

locationstringPays d'origine du numéro

lineTypestringType de ligne: mobile, landline, voip, toll-free

checkedAtstringDate/heure de la vérification (ISO 8601)

balancenumberVotre solde de crédits restant en euros

POST

/check/bulk

0.70€ x N numéros

Analysez jusqu'à 100 numéros en une seule requête. Idéal pour auditer une base de numéros existante.

Corps de la requête (JSON)

Champ	Type	Requis	Description
phoneNumbers	string[]	Oui	Tableau de numéros (max 100)
stopOnError	boolean	Non	Arrêter si un numéro est invalide (défaut: false)

{
  "phoneNumbers": [
    "+33612345678",
    "+33698765432",
    "+33611223344",
    "+33655667788"
  ],
  "stopOnError": false
}

Réponse JSON

{
  "success": true,
  "data": {
    "results": [
      {
        "phoneNumber": "+33612345678",
        "isSpam": true,
        "spamScore": 85,
        "spamType": "Telemarketing",
        "carrier": "Orange"
      },
      {
        "phoneNumber": "+33698765432",
        "isSpam": false,
        "spamScore": 12,
        "spamType": null,
        "carrier": "SFR"
      },
      {
        "phoneNumber": "+33611223344",
        "isSpam": true,
        "spamScore": 92,
        "spamType": "Scam",
        "carrier": "Free"
      }
    ],
    "summary": {
      "totalChecked": 4,
      "spamCount": 2,
      "cleanCount": 2,
      "errorCount": 0
    }
  },
  "balance": 11.50
}

Limites

• Maximum 100 numéros par requête
• Numéros dupliqués comptés une seule fois
• Numéros invalides ignorés (sauf si stopOnError: true)

Surveillance / Routines

Surveillez automatiquement vos numéros 24/7. Recevez des alertes dès qu'un numéro change de statut spam. Chaque vérification de routine coûte 0.70€.

POST/routinesCréer une surveillance

Champ	Type	Requis	Description
phoneNumber	string	Oui	Numéro à surveiller
name	string	Non	Nom personnalisé (ex: "Ligne commerciale 1")
intervalHours	number	Oui	Fréquence en heures (1, 4, 12, 24, 48, 72)
notifyVia	string[]	Non	Canaux: "email", "sms", "webhook", "discord"
notifyOnlyIfSpam	boolean	Non	Alerter uniquement si spam détecté (défaut: true)
notifyOnChange	boolean	Non	Alerter uniquement si le statut change (défaut: false)
webhookUrl	string	Non	URL webhook personnalisée pour cette routine

// Requête
{
  "phoneNumber": "+33612345678",
  "name": "Ligne commerciale Paris",
  "intervalHours": 24,
  "notifyVia": ["email", "webhook"],
  "notifyOnlyIfSpam": true,
  "notifyOnChange": true,
  "webhookUrl": "https://mon-crm.com/webhook/spam"
}

// Réponse
{
  "success": true,
  "data": {
    "id": "routine_abc123",
    "phoneNumber": "+33612345678",
    "name": "Ligne commerciale Paris",
    "intervalHours": 24,
    "nextCheckAt": "2026-01-25T10:30:00Z",
    "createdAt": "2026-01-24T10:30:00Z"
  }
}

POST/routines/bulkCréer plusieurs surveillances

Créez jusqu'à 50 routines en une seule requête avec les mêmes paramètres.

{
  "phoneNumbers": ["+33612345678", "+33698765432", "+33611223344"],
  "intervalHours": 24,
  "notifyVia": ["email"],
  "notifyOnlyIfSpam": true
}

GET/routinesLister les surveillances

Query Param	Description
page	Page (défaut: 1)
limit	Résultats par page (défaut: 20, max: 100)
status	Filtrer: "active", "paused", "all"
search	Recherche par numéro ou nom

PUT/routines/{id}Modifier une surveillance

Modifiez les paramètres d'une routine existante. Tous les champs de création sont modifiables.

{
  "intervalHours": 12,
  "notifyVia": ["email", "sms"],
  "paused": false
}

DELETE/routines/{id}Supprimer une surveillance

Supprime définitivement une routine. L'historique des vérifications reste disponible.

DELETE/routines/bulkSupprimer plusieurs surveillances

{
  "ids": ["routine_abc123", "routine_def456", "routine_ghi789"]
}

Historique

Consultez et exportez l'historique de toutes vos vérifications.

GET/history

Query Param	Type	Description
page	number	Page (défaut: 1)
limit	number	Résultats par page (défaut: 20, max: 100)
from	string	Date début (ISO 8601)
to	string	Date fin (ISO 8601)
isSpam	boolean	Filtrer par statut spam
phone	string	Recherche par numéro

// GET /history?page=1&limit=20&isSpam=true

{
  "success": true,
  "data": {
    "checks": [
      {
        "id": "check_123",
        "phoneNumber": "+33612345678",
        "isSpam": true,
        "spamScore": 85,
        "spamType": "Telemarketing",
        "carrier": "Orange",
        "source": "api",
        "checkedAt": "2026-01-24T10:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 156,
      "totalPages": 8
    }
  }
}

GET/history/export

Téléchargez votre historique en CSV ou JSON.

Query Param	Description
format	"csv" ou "json" (requis)
from	Date début (optionnel)
to	Date fin (optionnel)

Retourne un fichier à télécharger (Content-Type: text/csv ou application/json)

Crédits & Facturation

GET/credits/balance

Récupère votre solde de crédits actuel.

{
  "success": true,
  "data": {
    "balance": 47.60,
    "currency": "EUR"
  }
}

GET/credits/transactions

Historique de vos transactions (achats, consommations).

Query Param	Description
page, limit	Pagination
type	"credit" (achat) ou "debit" (consommation)

GET/credits/invoices

Liste de vos factures téléchargeables.

Webhooks

Recevez des notifications en temps réel sur votre serveur. Configurez votre endpoint dans le dashboard > Paramètres > Webhooks.

Payload envoyé (POST sur votre URL)

{
  "event": "spam_status_changed",
  "timestamp": "2026-01-24T10:30:00Z",
  "data": {
    "routineId": "routine_abc123",
    "phoneNumber": "+33612345678",
    "phoneName": "Ligne commerciale Paris",
    "previousStatus": {
      "isSpam": false,
      "spamScore": 15
    },
    "currentStatus": {
      "isSpam": true,
      "spamScore": 78,
      "spamType": "Telemarketing"
    }
  }
}

Événements disponibles

spam_status_changedLe statut spam d'un numéro surveillé a changé

routine_check_completedUne vérification de routine s'est terminée

routine_check_failedUne vérification de routine a échoué

credits_lowVotre solde est inférieur à 5€

credits_depletedVotre solde est à 0€

Sécurité

Chaque requête inclut un header de signature pour valider l'authenticité:

X-HUHU-Signature: sha256=...

HMAC SHA256 du body avec votre webhook secret

Retry Policy

• 3 tentatives maximum
• Délai: 1min, 5min, 15min
• Timeout: 10 secondes
• Codes success: 2xx

Codes Erreurs

400

BAD REQUEST

Format de numéro invalide ou paramètres manquants/incorrects.

401

UNAUTHORIZED

Token manquant, invalide ou expiré.

402

PAYMENT REQUIRED

Solde de crédits insuffisant pour cette opération.

403

FORBIDDEN

Accès refusé à cette ressource.

404

NOT FOUND

Ressource inexistante (routine, numéro...).

409

CONFLICT

Ressource déjà existante (routine en double...).

429

TOO MANY REQUESTS

Rate limit dépassé (10 req/sec). Réessayez après 1 seconde.

500

SERVER ERROR

Erreur interne. Contactez le support si persistant.

Format d'erreur

{
  "success": false,
  "error": "Insufficient credits",
  "code": "INSUFFICIENT_CREDITS",
  "details": {
    "required": 0.70,
    "balance": 0.35
  }
}

Besoin d'aide ?

Notre équipe technique peut vous aider à intégrer l'API dans votre CRM, Dialer ou système interne.

DOC API

Authentification

Récupérer votre token

Sécurité

/check/{phone}

Paramètres URL

Réponse JSON

Champs de la réponse

/check/bulk

Corps de la requête (JSON)

Réponse JSON

Limites

Surveillance / Routines

Historique

Crédits & Facturation

Webhooks

Payload envoyé (POST sur votre URL)

Événements disponibles

Sécurité

Retry Policy

Codes Erreurs

Format d'erreur

Besoin d'aide ?

Cookies & Confidentialité