Documentation · REST API

API DOC

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.: +33612345678)

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

Combined score computed by HUHU (Hiya + Truecaller)

isSpambooleantrue if the number is considered spam

spamScorenumberScore from 0 to 100 (100 = certain spam)

spamTypestringType: Telemarketing, Scam, Robocall…

numberTypestringMOBILE, FIXED_LINE, VOIP, PREMIUM_RATE

countryCodestringISO country code: FR, BE, CH…

carrierstringCarrier: Orange, SFR, Free, Bouygues…

hiya

Raw data from the Hiya API

reputationLevelstringpositive (safe), neutral, negative (spam)

truecaller

Raw data from the Truecaller API

spamScorenumberTruecaller score from 1 to 10

spamTypestringsales, scam, telemarketer, robocall…

numReportsnumberTotal number of reports

numReports60daysnumberReports over the last 60 days

orange

Raw data from the Orange Telephone API

isSpambooleantrue if the number is reported as spam

negativeReviewsnumberNumber of negative reviews (spam reports)

positiveReviewsnumberNumber of positive reviews (reliable number)

mainSpamTypestringMain type: SCAM, TELEMARKETING, etc.

spamTypesRepartitionarrayapi_doc.field_spamTypesRepartition

costnumberNumber of verifications used (always 1)

balancenumberRemaining verification balance

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	List of numbers (max 100)
stopOnError	boolean	No	Stop on first error (default: 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
}

Limits

• Maximum 100 numbers per request
• Numbers are processed in batches of 5 in parallel
• Only successful checks are billed

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

Create a monitoring routine for a number.

Field	Type	Required	Description
phoneNumber	string	Yes	Number to monitor
scheduleType	string	Yes	"interval" or "weekly"
intervalDays	number	if interval	Interval in days (1, 2, 7…)
weeklyDays	number[]	if weekly	Days: 0=Sun, 1=Mon, 2=Tue, 3=Wed, 4=Thu, 5=Fri, 6=Sat
notifyVia	string[]	No	["email", "sms", "discord", "webhook"]
notifyOnlyIfSpam	boolean	No	Notify only if spam (default: 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

Create multiple routines in a single request (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

Returns all your routines with the last known spam score.

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}

Update an existing routine.

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}

Delete a routine.

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

DELETE/routines/bulk

Delete multiple routines in a single request.

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 (default: 1)
limit	number	Results per page (default: 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

Export the full history as CSV or JSON.

Query Param	Description
format	"csv" or "json" (default: json)
from	Start date (ISO 8601)
to	End date (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

Returns the current verification balance.

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

Transaction history (verification additions/usage).

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

GET/credits/invoices

List of invoices with PDF download links.

Webhooks

Receive real-time notifications when the spam status of a number changes or when a routine runs.

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

Available Events

spam_status_changedThe spam status changed (spam → clean or clean → spam)

routine_check_completedA routine ran successfully

routine_check_failedA routine failed to run

credits_lowBalance below 5 verifications

credits_depletedBalance depleted (0 verifications)

Security

Every webhook is signed with your secret key.

X-HUHU-Signature: sha256=...

Verify the HMAC-SHA256 signature with your secret.

Retry policy

• Expected response: HTTP 2xx
• Timeout: 10 seconds
• Max 3 attempts (1min, 5min, 15min)
• Abandoned after 3 failures

Error Codes

The API uses standard HTTP codes. Each error returns a JSON with details.

400

BAD REQUEST

Missing or invalid parameters

401

UNAUTHORIZED

Missing or invalid API token

402

PAYMENT REQUIRED

Insufficient balance for this operation

404

NOT FOUND

Resource not found (routine, number…)

429

TOO MANY REQUESTS

Rate limit exceeded (max 10 req/sec)

500

SERVER ERROR

Internal error, try again later

Error Format

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

CONTACT SUPPORT Contact