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.

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

GET

/check/{phone}

€0.70 / verification

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

URL Parameters

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

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

JSON Response

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

Response Fields

phoneNumberstringAnalyzed number in international format

isSpambooleantrue if the number is identified as spam

spamScorenumberScore from 0 to 100 (0 = safe, 100 = certain spam)

spamTypestringSpam type: Telemarketing, Scam, Robocall, Survey, Unknown

carrierstringPhone carrier (Orange, SFR, Free, Bouygues...)

locationstringCountry of origin of the number

lineTypestringLine type: mobile, landline, voip, toll-free

checkedAtstringDate/time of the verification (ISO 8601)

balancenumberYour remaining credit balance in euros

POST

/check/bulk

€0.70 x N numbers

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	Array of numbers (max 100)
stopOnError	boolean	No	Stop if a number is invalid (default: false)

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

JSON Response

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

Limits

• Maximum 100 numbers per request
• Duplicate numbers counted only once
• Invalid numbers ignored (unless stopOnError: true)

Monitoring / Routines

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

POST/routinesCreate a monitoring routine

Field	Type	Required	Description
phoneNumber	string	Yes	Number to monitor
name	string	No	Custom name (e.g.: "Sales Line 1")
intervalHours	number	Yes	Frequency in hours (1, 4, 12, 24, 48, 72)
notifyVia	string[]	No	Channels: "email", "sms", "webhook", "discord"
notifyOnlyIfSpam	boolean	No	Alert only if spam detected (default: true)
notifyOnChange	boolean	No	Alert only if status changes (default: false)
webhookUrl	string	No	Custom webhook URL for this 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/bulkCreate multiple monitoring routines

Create up to 50 routines in a single request with the same parameters.

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

GET/routinesList monitoring routines

Query Param	Description
page	Page (default: 1)
limit	Results per page (default: 20, max: 100)
status	Filter: "active", "paused", "all"
search	Search by number or name

PUT/routines/{id}Update a monitoring routine

Modify the parameters of an existing routine. All creation fields are editable.

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

DELETE/routines/{id}Delete a monitoring routine

Permanently deletes a routine. Verification history remains available.

DELETE/routines/bulkDelete multiple monitoring routines

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

History

View and export the history of all your verifications.

GET/history

Query Param	Type	Description
page	number	Page (default: 1)
limit	number	Results per page (default: 20, max: 100)
from	string	Start date (ISO 8601)
to	string	End date (ISO 8601)
isSpam	boolean	Filter by spam status
phone	string	Search by number

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

Download your history in CSV or JSON.

Query Param	Description
format	"csv" or "json" (required)
from	Start date (optional)
to	End date (optional)

Returns a downloadable file (Content-Type: text/csv or application/json)

Credits & Billing

GET/credits/balance

Retrieve your current credit balance.

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

GET/credits/transactions

History of your transactions (purchases, usage).

Query Param	Description
page, limit	Pagination
type	"credit" (purchase) or "debit" (usage)

GET/credits/invoices

List of your downloadable invoices.

Webhooks

Receive real-time notifications on your server. Configure your endpoint in dashboard > Settings > Webhooks.

Payload sent (POST to your 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"
    }
  }
}

Available Events

spam_status_changedThe spam status of a monitored number has changed

routine_check_completedA routine check has completed

routine_check_failedA routine check has failed

credits_lowYour balance is below €5

credits_depletedYour balance is at €0

Security

Each request includes a signature header to validate authenticity:

X-HUHU-Signature: sha256=...

HMAC SHA256 of the body with your webhook secret

Retry Policy

• 3 attempts maximum
• Delay: 1min, 5min, 15min
• Timeout: 10 seconds
• Success codes: 2xx

Error Codes

400

BAD REQUEST

Invalid number format or missing/incorrect parameters.

401

UNAUTHORIZED

Missing, invalid or expired token.

402

PAYMENT REQUIRED

Insufficient credit balance for this operation.

403

FORBIDDEN

Access denied to this resource.

404

NOT FOUND

Resource not found (routine, number...).

409

CONFLICT

Resource already exists (duplicate routine...).

429

TOO MANY REQUESTS

Rate limit exceeded (10 req/sec). Retry after 1 second.

500

SERVER ERROR

Internal error. Contact support if persistent.

Error Format

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

Need help?

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

DOC API

Authentication

Get your token

Security

/check/{phone}

URL Parameters

JSON Response

Response Fields

/check/bulk

Request Body (JSON)

JSON Response

Limits

Monitoring / Routines

History

Credits & Billing

Webhooks

Payload sent (POST to your URL)

Available Events

Security

Retry Policy

Error Codes

Error Format

Need help?

Cookies & Privacy