Documentation · REST API

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.

curl -X POST "https://num.huhu.fr/api/auth/regenerate-token" \
  -H "Authorization: Bearer spk_live_xxxxxxxxxxxx"

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

GET

/check/{phone}

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	Description
phone	string	Numéro au format international (ex: +33612345678)

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

Réponse JSON

{
  "success": true,
  "data": {
    "phoneNumber": "+33612345678",
    "huhu": {
      "isSpam": true,
      "spamScore": 85,
      "spamType": "Telemarketing",
      "numberType": "MOBILE",
      "countryCode": "FR",
      "carrier": "Orange",
      "lineType": "MOBILE_mobile"
    },
    "hiya": {
      "reputationLevel": "negative"
    },
    "truecaller": {
      "spamScore": 7,
      "spamType": "sales",
      "numReports": 150,
      "numReports60days": 45
    },
    "orange": {
      "isSpam": true,
      "negativeReviews": 64,
      "positiveReviews": 0,
      "mainSpamType": "SCAM",
      "spamTypesRepartition": [
        {"category": "SCAM", "ratio": 0.89},
        {"category": "TELEMARKETING", "ratio": 0.11}
      ]
    }
  },
  "cost": 1,
  "balance": 14
}

Champs de la réponse

huhu

Score combiné calculé par HUHU (Hiya + Truecaller)

isSpambooleantrue si le numéro est considéré spam

spamScorenumberScore de 0 à 100 (100 = spam certain)

spamTypestringType : Telemarketing, Scam, Robocall…

numberTypestringMOBILE, FIXED_LINE, VOIP, PREMIUM_RATE

countryCodestringCode pays ISO : FR, BE, CH…

carrierstringOpérateur : Orange, SFR, Free, Bouygues…

hiya

Données brutes de l'API Hiya

reputationLevelstringpositive (sûr), neutral, negative (spam)

truecaller

Données brutes de l'API Truecaller

spamScorenumberScore Truecaller de 1 à 10

spamTypestringsales, scam, telemarketer, robocall…

numReportsnumberNombre total de signalements

numReports60daysnumberSignalements des 60 derniers jours

orange

Données brutes de l'API Orange Telephone

isSpambooleantrue si le numéro est signalé spam

negativeReviewsnumberNombre d'avis négatifs (signalements spam)

positiveReviewsnumberNombre d'avis positifs (numéro fiable)

mainSpamTypestringType principal : SCAM, TELEMARKETING, etc.

spamTypesRepartitionarrayapi_doc.field_spamTypesRepartition

costnumberNombre de vérifications utilisées (toujours 1)

balancenumberSolde de vérifications restant

POST

/check/bulk

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	Liste des numéros (max 100)
stopOnError	boolean	Non	Arrêter au premier échec (défaut : false)

curl -X POST "https://num.huhu.fr/api/check/bulk" \
  -H "Authorization: Bearer spk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumbers": ["+33612345678", "+33698765432"],
    "stopOnError": false
  }'

Réponse JSON

{
  "success": true,
  "data": {
    "results": [
      {
        "phoneNumber": "+33612345678",
        "huhu": { "isSpam": true, "spamScore": 85, ... },
        "hiya": { "reputationLevel": "negative" },
        "truecaller": { "spamScore": 7, "numReports": 150, ... },
        "orange": { "isSpam": true, "negativeReviews": 64, ... }
      },
      ...
    ],
    "summary": {
      "totalChecked": 10,
      "spamCount": 3,
      "cleanCount": 7,
      "errorCount": 0
    }
  },
  "cost": 10,
  "unitCost": 1,
  "balance": 40
}

Limites

• Maximum 100 numéros par requête
• Les numéros sont traités par lot de 5 en parallèle
• Seuls les checks réussis sont facturés

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.35€.

POST/routines

Créer une routine de surveillance pour un numéro.

Champ	Type	Requis	Description
phoneNumber	string	Oui	Numéro à surveiller
scheduleType	string	Oui	"interval" ou "weekly"
intervalDays	number	si interval	Intervalle en jours (1, 2, 7…)
weeklyDays	number[]	si weekly	Jours : 0=Dim, 1=Lun, 2=Mar, 3=Mer, 4=Jeu, 5=Ven, 6=Sam
notifyVia	string[]	Non	["email", "sms", "discord", "webhook"]
notifyOnlyIfSpam	boolean	Non	Notifier uniquement si spam (défaut : true)

curl -X POST "https://num.huhu.fr/api/routines" \
  -H "Authorization: Bearer spk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+33612345678",
    "scheduleType": "interval",
    "intervalDays": 7,
    "notifyVia": ["email"],
    "notifyOnlyIfSpam": true
  }'

// Response
{
  "success": true,
  "data": {
    "id": "67890abc",
    "phoneNumber": "+33612345678",
    "scheduleType": "interval",
    "intervalDays": 7,
    "notifyVia": ["email"],
    "notifyOnlyIfSpam": true,
    "isActive": true,
    "nextRun": "2026-01-31T09:00:00Z"
  },
  "balance": 47
}

POST/routines/bulk

Créer plusieurs routines en une seule requête (max 100).

curl -X POST "https://num.huhu.fr/api/routines/bulk" \
  -H "Authorization: Bearer spk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumbers": ["+33612345678", "+33698765432"],
    "defaultSettings": {
      "scheduleType": "weekly",
      "weeklyDays": [1, 4],
      "notifyVia": ["email"]
    }
  }'

GET/routines

Récupère toutes vos routines avec le dernier score spam connu.

curl -X GET "https://num.huhu.fr/api/routines" \
  -H "Authorization: Bearer spk_live_xxxxxxxxxxxx"

{
  "success": true,
  "data": {
    "routines": [
      {
        "id": "67890abc",
        "phoneNumber": "+33612345678",
        "scheduleType": "interval",
        "intervalDays": 7,
        "notifyVia": ["email"],
        "notifyOnlyIfSpam": true,
        "isActive": true,
        "lastRun": "2026-01-24T09:00:00Z",
        "nextRun": "2026-01-31T09:00:00Z",
        "lastScore": 85,
        "lastCheckedAt": "2026-01-24T09:00:00Z"
      }
    ]
  }
}

PUT/routines/{id}

Modifier une routine existante.

curl -X PUT "https://num.huhu.fr/api/routines/ROUTINE_ID" \
  -H "Authorization: Bearer spk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "intervalDays": 3,
    "isActive": false
  }'

DELETE/routines/{id}

Supprimer une routine.

curl -X DELETE "https://num.huhu.fr/api/routines/ROUTINE_ID" \
  -H "Authorization: Bearer spk_live_xxxxxxxxxxxx"

DELETE/routines/bulk

Supprimer plusieurs routines en une requête.

curl -X DELETE "https://num.huhu.fr/api/routines/bulk" \
  -H "Authorization: Bearer spk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["id1", "id2", "id3"] }'

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)

curl -X GET "https://num.huhu.fr/api/history?page=1&limit=20" \
  -H "Authorization: Bearer spk_live_xxxxxxxxxxxx"

{
  "success": true,
  "data": {
    "history": [
      {
        "id": "67890abc",
        "phoneNumber": "+33612345678",
        "isSpam": true,
        "spamScore": 85,
        "spamType": "Telemarketing",
        "cost": 1,
        "checkedAt": "2026-01-24T10:30:00Z",
        "huhu": { ... },
        "hiya": { ... },
        "truecaller": { ... },
        "orange": { ... }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 156,
      "totalPages": 8
    }
  }
}

GET/history/export

Exporter l'historique complet en CSV ou JSON.

Query Param	Description
format	"csv" ou "json" (défaut : json)
from	Date de début (ISO 8601)
to	Date de fin (ISO 8601)

curl -X GET "https://num.huhu.fr/api/history/export?format=csv" \
  -H "Authorization: Bearer spk_live_xxxxxxxxxxxx" \
  -o export.csv

Crédits & Facturation

GET/credits/balance

Récupère le solde actuel de vérifications.

curl -X GET "https://num.huhu.fr/api/credits/balance" \
  -H "Authorization: Bearer spk_live_xxxxxxxxxxxx"

{
  "success": true,
  "data": {
    "balance": 47,
    "checkPrice": 1
  }
}

GET/credits/transactions

Historique des transactions (ajouts/utilisations de vérifications).

curl -X GET "https://num.huhu.fr/api/credits/transactions?page=1&limit=20" \
  -H "Authorization: Bearer spk_live_xxxxxxxxxxxx"

GET/credits/invoices

Liste des factures avec liens de téléchargement PDF.

Webhooks

Recevez des notifications en temps réel lorsque le statut spam d'un numéro change ou lorsqu'une routine s'exécute.

Payload envoyé (POST sur votre URL)

POST https://votre-serveur.com/webhook

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

Événements disponibles

spam_status_changedLe statut spam a changé (spam → clean ou clean → spam)

routine_check_completedUne routine s'est exécutée avec succès

routine_check_failedÉchec d'exécution d'une routine

credits_lowSolde inférieur à 5 vérifications

credits_depletedSolde épuisé (0 vérification)

Sécurité

Chaque webhook est signé avec votre clé secrète.

X-HUHU-Signature: sha256=...

Vérifiez la signature HMAC-SHA256 avec votre secret.

Politique de retry

• Réponse attendue : HTTP 2xx
• Timeout : 10 secondes
• 3 tentatives max (1min, 5min, 15min)
• Abandon après 3 échecs

Codes Erreurs

L'API utilise les codes HTTP standards. Chaque erreur retourne un JSON avec le détail.

400

BAD REQUEST

Paramètres manquants ou invalides

401

UNAUTHORIZED

Token API manquant ou invalide

402

PAYMENT REQUIRED

Solde insuffisant pour cette opération

404

NOT FOUND

Ressource introuvable (routine, numéro…)

429

TOO MANY REQUESTS

Rate limit dépassé (max 10 req/sec)

500

SERVER ERROR

Erreur interne, réessayez plus tard

Format d'erreur

{
  "success": false,
  "error": "Insufficient verifications",
  "code": "INSUFFICIENT_VERIFICATIONS",
  "details": {
    "required": 1,
    "balance": 0
  }
}

Besoin d'aide ?

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

CONTACTER LE SUPPORT Contact