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.

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 combine calcule par HUHU (Hiya + Truecaller)

isSpambooleantrue si le numero est considere spam

spamScorenumberScore de 0 a 100 (100 = spam certain)

spamTypestringType: Telemarketing, Scam, Robocall...

numberTypestringMOBILE, FIXED_LINE, VOIP, PREMIUM_RATE

countryCodestringCode pays ISO: FR, BE, CH...

carrierstringOperateur: Orange, SFR, Free, Bouygues...

hiya

Donnees brutes de l'API Hiya

reputationLevelstringpositive (sur), neutral, negative (spam)

truecaller

Donnees brutes de l'API Truecaller

spamScorenumberScore Truecaller de 1 a 10

spamTypestringsales, scam, telemarketer, robocall...

numReportsnumberNombre total de signalements

numReports60daysnumberSignalements des 60 derniers jours

orange

Donnees brutes de l'API Orange Telephone

isSpambooleantrue si le numero est signale spam

negativeReviewsnumberNombre d'avis negatifs (signalements spam)

positiveReviewsnumberNombre d'avis positifs (numero fiable)

mainSpamTypestringType principal: SCAM, TELEMARKETING, etc.

spamTypesRepartitionarrayRepartition des types [{category, ratio}]

costnumberNombre de verifications utilisees (toujours 1)

balancenumberSolde de verifications 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 numeros (max 100)
stopOnError	boolean	Non	Arreter au premier echec (defaut: 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 numeros par requete
• Les numeros sont traites par lot de 5 en parallele
• Seuls les checks reussis sont factures

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

Creer une routine de surveillance pour un numero.

Champ	Type	Requis	Description
phoneNumber	string	Oui	Numero a 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 (defaut: 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
  }'

// Reponse
{
  "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

Creer plusieurs routines en une seule requete (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

Recupere 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 requete.

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 (defaut: 1)
limit	number	Resultats par page (defaut: 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" (defaut: json)
from	Date de debut (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

Recupere le solde actuel de verifications.

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 verifications).

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 telechargement PDF.

Webhooks

Recevez des notifications en temps reel lorsque le statut spam d'un numero change ou lorsqu'une routine s'execute.

Payload envoye

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"
    }
  }
}

Evenements disponibles

spam_status_changedLe statut spam a change (spam -> clean ou clean -> spam)

routine_check_completedUne routine s'est executee avec succes

routine_check_failedEchec d'execution d'une routine

credits_lowSolde inferieur a 5 verifications

credits_depletedSolde epuise (0 verification)

Securite

Chaque webhook est signe avec votre cle secrete.

X-HUHU-Signature: sha256=...

Verifiez la signature HMAC-SHA256 avec votre secret.

Politique de retry

• Reponse attendue: HTTP 2xx
• Timeout: 10 secondes
• 3 tentatives max (1min, 5min, 15min)
• Abandon apres 3 echecs

Codes Erreurs

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

400

BAD REQUEST

Parametres manquants ou invalides

401

UNAUTHORIZED

Token API manquant ou invalide

402

PAYMENT REQUIRED

Solde insuffisant pour cette operation

404

NOT FOUND

Ressource introuvable (routine, numero...)

429

TOO MANY REQUESTS

Rate limit depasse (max 10 req/sec)

500

SERVER ERROR

Erreur interne, reessayez plus tard

Format des erreurs

{
  "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.