API Reference v1.0

DOC API

Integrate spam verification directly into your call centers, CRM and dialers. Simple, fast and reliable REST API.

Authentication

All requests require a Bearer token. Retrieve your token from your dashboard > API.

REQUIRED HTTP HEADER

Authorization: Bearer spk_live_xxxxxxxxxxxx

Get your token

Log in to your dashboard
Go to "API" in the menu
Copy your token or regenerate a new one

Security

• Never share your token
• Regenerate it if compromised
• Use environment variables

POST/auth/regenerate-token

Regenerates your API token. The old token becomes immediately invalid.

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}

Instant analysis of a phone number. Returns the spam score, spam type, carrier and location.

URL Parameters

Parameter	Type	Description
phone	string	Number in international format (e.g.: +1612345678)

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

JSON Response

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

Response Fields

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

Analyze up to 100 numbers in a single request. Ideal for auditing an existing number database.

Request Body (JSON)

Field	Type	Required	Description
phoneNumbers	string[]	Yes	Liste des numeros (max 100)
stopOnError	boolean	No	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
  }'

JSON Response

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

Monitoring / Routines

Automatically monitor your numbers 24/7. Receive alerts as soon as a number changes spam status. Each routine check costs $0.35.

POST/routines

Creer une routine de surveillance pour un numero.

Field	Type	Required	Description
phoneNumber	string	Yes	Numero a surveiller
scheduleType	string	Yes	"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[]	No	["email", "sms", "discord", "webhook"]
notifyOnlyIfSpam	boolean	No	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"] }'

History

View and export the history of all your verifications.

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

Credits & Billing

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

Error Codes

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

Need help?

Our technical team can help you integrate the API into your CRM, Dialer or internal system.