{"openapi":"3.1.0","info":{"title":"ScamCallCheck Public Data API","version":"1.0.0","description":"Read-only access to phone-number records and monthly aggregates with community reports kept separate from public-agency complaint totals. Methodology: https://scamcallcheck.com/methodology"},"servers":[{"url":"https://scamcallcheck.com"}],"paths":{"/api/number/{e164}":{"get":{"operationId":"getNumberReports","summary":"Look up reports for a phone number","description":"Returns a risk summary, community reports, source-labelled public complaint totals, the canonical page, and a link where a human can contribute their own experience.","parameters":[{"name":"e164","in":"path","required":true,"description":"Digits-only canonical E.164 number, including country code.","schema":{"type":"string","pattern":"^[0-9]{8,15}$","examples":["13692166437"]}}],"responses":{"200":{"description":"Number lookup result","content":{"application/json":{"schema":{"type":"object","required":["schemaVersion","phoneNumber","risk","community","links","disclaimer"],"properties":{"schemaVersion":{"type":"string"},"phoneNumber":{"type":"object"},"risk":{"type":"object"},"community":{"type":"object"},"publicAgencyComplaints":{"type":"object"},"lastActivityAt":{"type":["string","null"],"format":"date-time"},"links":{"type":"object"},"disclaimer":{"type":"string"}}}}}},"400":{"description":"Invalid or non-canonical number"}}}},"/api/reports/{month}":{"get":{"operationId":"getMonthlyActivityReport","summary":"Get a monthly aggregate activity report","description":"Returns FTC/FCC complaint totals, published community-report totals, leading categories, and active phone numbers for one calendar month.","parameters":[{"name":"month","in":"path","required":true,"description":"UTC calendar month in YYYY-MM format.","schema":{"type":"string","pattern":"^[0-9]{4}-(0[1-9]|1[0-2])$","examples":["2026-08"]}}],"responses":{"200":{"description":"Monthly aggregate report","content":{"application/json":{"schema":{"type":"object","required":["schemaVersion","period","counts","categories","topNumbers","provenance","disclaimer"],"properties":{"schemaVersion":{"type":"string"},"period":{"type":"object"},"counts":{"type":"object"},"categories":{"type":"array","items":{"type":"object"}},"topNumbers":{"type":"array","items":{"type":"object"}},"provenance":{"type":"object"},"disclaimer":{"type":"string"}}}}}},"400":{"description":"Invalid month"},"404":{"description":"No activity for that month"}}}},"/api/v1/lookup":{"post":{"operationId":"bulkLookup","summary":"Look up many numbers in one request (paid)","description":"Up to 100 numbers per request in any common format. Each parseable number costs one lookup against the monthly quota. Returns the stored risk score and counts; follow links.detail for full report text. Plans: https://scamcallcheck.com/developers","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["numbers"],"properties":{"numbers":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Per-number results with quota headers"},"400":{"description":"Malformed body"},"401":{"description":"Missing or unknown key"},"402":{"description":"Subscription past due"},"429":{"description":"Monthly quota exhausted"}}}},"/api/v1/feed":{"get":{"operationId":"flaggedFeed","summary":"Feed of flagged numbers (paid, Pro plan)","description":"Every number with at least one published community report or two or more public-agency complaints, most recent activity first. One request costs one lookup regardless of page size.","security":[{"apiKey":[]}],"parameters":[{"name":"since","in":"query","schema":{"type":"string","format":"date"},"description":"Only numbers with activity on or after this date."},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000,"default":500}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","csv"],"default":"json"}}],"responses":{"200":{"description":"Rows as JSON or CSV"},"401":{"description":"Missing or unknown key"},"403":{"description":"Plan does not include the feed"},"429":{"description":"Monthly quota exhausted"}}}},"/api/v1/usage":{"get":{"operationId":"getUsage","summary":"Plan, quota and current-month usage for a key","security":[{"apiKey":[]}],"responses":{"200":{"description":"Usage summary"},"401":{"description":"Missing or unknown key"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Keys are issued at https://scamcallcheck.com/developers and look like scc_live_… . X-API-Key is accepted as an alternative header."}}}}