{"openapi":"3.1.0","info":{"title":"PhonkinSpam API","version":"1.0.0","summary":"Community reputation of a French phone number: safe, suspect or dangerous.","description":"Free, public, key-less API. Read-only. Rate limit: 1 request per second per IP.\n\nThe status aggregates reports from the PhonkinSpam community. It is indicative and is neither a verification nor an accusation.","contact":{"url":"http:\/\/phonkinspam.com\/api"}},"servers":[{"url":"http:\/\/phonkinspam.com"}],"x-ratelimit":{"policy":"token_bucket","rate":"1\/second per IP","burst":1,"on_exceeded":"HTTP 429 + Retry-After header"},"paths":{"\/api\/v1\/number\/{number}":{"get":{"operationId":"lookupNumber","summary":"Reputation of a number","description":"Returns the status (safe\/suspect\/dangerous) and the community-signal details for a French number. An unknown number returns 200 with known=false and status=safe.","parameters":[{"name":"number","in":"path","required":true,"description":"French number: national (0XXXXXXXXX), international without + (33XXXXXXXXX) or E.164 (+33XXXXXXXXX).","schema":{"type":"string","pattern":"^\\+?\\d{9,12}$","example":"0162000000"}}],"responses":{"200":{"description":"Valid number. Status returned.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/NumberStatus"},"example":{"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":"\u00cele-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, agr\u00e9g\u00e9 \u00e0 partir de signalements d\u0027utilisateurs. Ne constitue ni une v\u00e9rification, ni une accusation \u00e0 l\u0027encontre du titulaire du num\u00e9ro."}}}},"400":{"description":"Invalid French number.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"},"example":{"error":{"code":"invalid_number","message":"Num\u00e9ro de t\u00e9l\u00e9phone fran\u00e7ais invalide."}}}}},"429":{"description":"Rate limit exceeded (more than 1 req\/s). Retry-After header present.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds before retrying."}},"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"},"example":{"error":{"code":"rate_limited","message":"D\u00e9bit d\u00e9pass\u00e9 : 1 requ\u00eate par seconde maximum."}}}}}}}},"\/api\/v1\/health":{"get":{"operationId":"health","summary":"Liveness probe","responses":{"200":{"description":"Service available.","content":{"application\/json":{"example":{"status":"ok","version":"v1"}}}}}}}},"components":{"schemas":{"NumberStatus":{"type":"object","required":["number","e164","national","status","score","spam_ratio","report_count","known","type","region","is_demarchage_range","url","source","disclaimer"],"properties":{"number":{"type":"string","description":"Normalized national format (0XXXXXXXXX)."},"e164":{"type":"string","description":"E.164 format (+33XXXXXXXXX)."},"national":{"type":"string","description":"Readable national format, grouped in pairs."},"status":{"type":"string","enum":["safe","suspect","dangerous"],"description":"safe = no notable signal; suspect = score \u003E= 2.5; dangerous = score \u003E= 6."},"score":{"type":"number","format":"float","minimum":0,"maximum":10,"description":"Danger score 0-10."},"spam_ratio":{"type":"number","format":"float","minimum":0,"maximum":1,"description":"Share of votes flagging the number as spam (0-1)."},"report_count":{"type":"integer","description":"Number of community reports."},"known":{"type":"boolean","description":"true if at least one report exists. false = no data, not a proof of trustworthiness."},"type":{"type":"string","enum":["fixe","mobile","voip","special"],"description":"Line type inferred from the prefix."},"operator":{"type":["string","null"],"description":"Operator if known."},"region":{"type":["string","null"],"description":"Region\/area inferred from the prefix."},"is_demarchage_range":{"type":"boolean","description":"true if the number belongs to an ARCEP range reserved for cold calling."},"first_reported_at":{"type":["string","null"],"format":"date-time","description":"First report (ISO-8601) or null."},"last_reported_at":{"type":["string","null"],"format":"date-time","description":"Last report (ISO-8601) or null."},"url":{"type":"string","format":"uri","description":"Public page for the number on PhonkinSpam."},"source":{"type":"string","description":"Data origin."},"disclaimer":{"type":"string","description":"Legal notice: indicative community-sourced data."}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_number","rate_limited"]},"message":{"type":"string"}}}}}}}}