API PhonkinSpam

Une seule requête, un verdict : safe, suspect ou dangerous pour n'importe quel numéro français. Gratuite, sans clé, en lecture seule.

Pour les IA / For AI agents

Résumé compact et auto-suffisant du contrat. Spec machine : /api/openapi.json (OpenAPI 3.1).

PhonkinSpam API - machine-readable summary
Base URL : http://phonkinspam.com
Auth     : none (free, no API key)
Limits   : 1 request / second / IP  ->  HTTP 429 + Retry-After header

Endpoint : GET /api/v1/number/{number}
  {number} = French phone number, any of:
             national 0XXXXXXXXX | international 33XXXXXXXXX | E.164 +33XXXXXXXXX

200 application/json (schema NumberStatus):
  status              "safe" | "suspect" | "dangerous"   # the verdict
  score               number 0..10                       # danger score
  spam_ratio          number 0..1
  report_count        integer
  known               boolean   # false = no community data (NOT a safety guarantee)
  type                "fixe" | "mobile" | "voip" | "special"
  is_demarchage_range boolean   # number is in an ARCEP cold-calling range
  number,e164,national,operator,region,
  first_reported_at,last_reported_at (ISO-8601|null),url,source,disclaimer

Unknown number       -> 200 with status="safe", known=false
Errors               -> 400 invalid_number | 429 rate_limited
                        envelope: {"error":{"code":"...","message":"..."}}

Example:
  curl http://phonkinspam.com/api/v1/number/0162000000
Spec : GET /api/openapi.json   |   Health: GET /api/v1/health

Présentation

L'API renvoie la réputation communautaire d'un numéro de téléphone français à partir des signalements publiés sur PhonkinSpam. Elle est pensée pour être intégrée dans une application, un standard téléphonique, un bot ou un assistant IA.

Aucune inscription, aucune clé. Vous interrogez directement l'URL. L'API ne modifie jamais la base : elle ne crée pas de fiche et ne compte pas votre requête comme une recherche.

Limites d'usage

1 requête par seconde et par adresse IP. Au-delà, la réponse est un code 429 accompagné d'un en-tête Retry-After (en secondes). Espacez vos appels d'au moins une seconde, ou respectez le délai indiqué.

Point d'entrée

GET http://phonkinspam.com/api/v1/number/{number}

{number} accepte les formats : national 0162000000, international 33162000000 ou E.164 +33162000000. Seuls les numéros français sont reconnus.

Réponse

Code 200, corps application/json :

Champ	Type	Description
status	string	Le verdict : `safe`, `suspect` ou `dangerous`.
score	number	Score de dangerosité de 0 à 10.
spam_ratio	number	Part des votes « spam » (0 à 1).
report_count	integer	Nombre de signalements communautaires.
known	boolean	`true` si au moins un signalement existe. `false` = absence de donnée, pas une garantie de fiabilité.
type	string	`fixe`, `mobile`, `voip` ou `special`.
is_demarchage_range	boolean	`true` si le numéro relève d'une plage ARCEP réservée au démarchage téléphonique.
operator	string \| null	Opérateur si connu.
region	string \| null	Zone géographique déduite du préfixe.
first_reported_at last_reported_at	string \| null	Dates ISO-8601 du premier et du dernier signalement, ou `null`.
number / e164 / national	string	Le numéro dans les trois formats.
url	string	Fiche publique du numéro sur PhonkinSpam.
disclaimer	string	Avertissement légal (donnée communautaire indicative).

Les trois statuts

safe - aucun signal notable (score < 2,5). Pour un numéro jamais signalé, known vaut false : c'est une absence de donnée, pas un certificat de confiance.

suspect - signalé par la communauté, sans atteindre le seuil critique (score ≥ 2,5).

dangerous - fortement signalé (score ≥ 6). À traiter avec prudence.

Exemple de réponse

{
  "number": "0162000000",
  "e164": "+33162000000",
  "national": "01 62 00 00 00",
  "status": "dangerous",
  "score": 7.4,
  "spam_ratio": 0.86,
  "report_count": 128,
  "known": true,
  "type": "fixe",
  "operator": null,
  "region": "Île-de-France",
  "is_demarchage_range": true,
  "first_reported_at": "2025-11-02T09:14:00+00:00",
  "last_reported_at": "2026-06-20T18:42:00+00:00",
  "url": "http://phonkinspam.com/numero/33162000000",
  "source": "phonkinspam-community",
  "disclaimer": "Score communautaire indicatif…"
}

Exemples d'appel

cURL

curl -s http://phonkinspam.com/api/v1/number/0162000000

JavaScript (fetch)

const r = await fetch("http://phonkinspam.com/api/v1/number/0162000000");
const data = await r.json();
console.log(data.status); // "safe" | "suspect" | "dangerous"

Python (requests)

import requests
data = requests.get("http://phonkinspam.com/api/v1/number/0162000000").json()
print(data["status"])

Erreurs

400 invalid_number - le numéro n'est pas un numéro français valide.

429 rate_limited - plus d'une requête par seconde ; réessayez après le délai Retry-After.

Toutes les erreurs suivent la même enveloppe :

{ "error": { "code": "invalid_number", "message": "Numéro de téléphone français invalide." } }

Mentions légales

Le statut et le score sont issus d'un calcul automatique agrégeant les signalements des utilisateurs. Ils traduisent une perception collective et ne constituent ni un constat vérifié, ni une accusation à l'encontre du titulaire du numéro. Recoupez l'information avant toute décision et signalez les numéros indésirables au 33700 ou à Bloctel. Voir les CGU.