REST APIv1JSON

API SprawdzamNumer

Reputacja numeru telefonu jednym zapytaniem

Sprawdź wynik zaufania, kategorię i społecznościowe opinie o dowolnym polskim numerze telefonu, prosto z poziomu swojej aplikacji. Jeden endpoint GET, odpowiedź w formacie JSON, dostęp na klucz API.

Do czego służy API?

API udostępnia te same dane, które widzisz na stronie numeru, w formie gotowej do integracji. Typowe zastosowania:

Contact center

Pokaż konsultantowi reputację numeru, zanim odbierze lub oddzwoni na połączenie.

Antyfraud i scoring

Wzbogać ocenę ryzyka o społecznościowe sygnały spamu, scamu i windykacji.

CRM i wzbogacanie danych

Dołącz wynik zaufania i kategorię do rekordów kontaktów w swojej bazie.

Aplikacje i integracje

Zbuduj funkcję rozpoznawania dzwoniącego w aplikacji mobilnej lub webowej.

Szybki start

Wszystkie zapytania kierujesz na bazowy adres https://www.sprawdzamnumer.pl/api/v1. Wystarczy jedno wywołanie GET z kluczem API w nagłówku:

bash

curl https://www.sprawdzamnumer.pl/api/v1/numbers/48500111222 \
  -H "Authorization: Bearer YOUR_API_KEY"

Przykładowa odpowiedź:

JSON

{
  "number": "+48 500 111 222",
  "e164": "+48500111222",
  "trust_score": 12,
  "rating": 1,
  "trust_label": "Niebezpieczny",
  "category": "spam",
  "category_label": "Spam",
  "verdict": "dangerous",
  "verdict_label": "NIEBEZPIECZNY",
  "spam_pct": 87,
  "vote_count": 142,
  "comment_count": 38,
  "operator": "Plus / Polkomtel",
  "prefix": "500",
  "last_activity": "2026-05-28T14:21:00Z",
  "url": "https://www.sprawdzamnumer.pl/numer/48500111222"
}

Uwierzytelnianie

Każde zapytanie wymaga klucza API przekazanego w nagłówku Authorization jako token typu Bearer:

nagłówek

Authorization: Bearer YOUR_API_KEY

Jak zdobyć klucz API?

Dostęp przyznajemy indywidualnie. Napisz do nas, opisz krótko swój przypadek użycia, a wyślemy Ci klucz wraz z limitami.

Poproś o dostęp

Endpoint

GET/api/v1/numbers/{number}

Zwraca aktualną reputację numeru telefonu. Parametr number przyjmujemy w dowolnym z formatów: +48500111222, 48500111222, 0048500111222 lub 500111222. Zapis normalizujemy automatycznie.

Pola odpowiedzi

Pole	Typ	Opis
`number`	string	Numer w formacie czytelnym, np. +48 500 111 222.
`e164`	string	Numer w międzynarodowym formacie E.164, np. +48500111222.
`trust_score`	integer	Wynik zaufania od 0 do 100. Im wyższy, tym bezpieczniejszy numer.
`rating`	number	Ocena od 1 do 5 wyliczona z wyniku zaufania, wygodna do gwiazdek.
`trust_label`	string	Etykieta słowna: Zaufany, Przeważnie bezpieczny, Nieznany, Podejrzany, Niebezpieczny.
`category`	string	Kategoria: spam, business, safe, unknown, debt_collection, telemarketing, government.
`category_label`	string	Etykieta kategorii po polsku, np. Spam, Windykacja.
`verdict`	string	Dominująca opinia: dangerous, annoying, neutral, useful, safe, unknown.
`verdict_label`	string	Etykieta werdyktu po polsku, np. NIEBEZPIECZNY.
`spam_pct`	integer	Procent głosów oznaczających spam lub nękanie, od 0 do 100.
`vote_count`	integer	Łączna liczba oddanych głosów.
`comment_count`	integer	Liczba zatwierdzonych komentarzy.
`operator`	string	Operator lub obszar wg prefiksu, np. Plus / Polkomtel, Warszawa.
`prefix`	string	Prefiks numeru, np. 500 (komórka) lub 22 (numer stacjonarny).
`last_activity`	string (ISO 8601)	Czas ostatniej aktywności: głosu lub komentarza.
`url`	string	Adres strony numeru w serwisie SprawdzamNumer.pl.

Kody odpowiedzi i błędy

200 OK

Zwrócono dane numeru.

400 Bad Request

Nieprawidłowy format numeru telefonu.

401 Unauthorized

Brak lub nieprawidłowy klucz API.

404 Not Found

Numer nie został jeszcze oceniony w serwisie.

429 Too Many Requests

Przekroczono limit zapytań dla klucza.

Błędy zwracamy w spójnej strukturze JSON z polami error oraz message:

401: brak klucza

JSON

{
  "error": "unauthorized",
  "message": "Wymagany klucz API."
}

404: numer nieoceniony

JSON

{
  "error": "not_found",
  "message": "Numer nie został jeszcze oceniony."
}

Limity zapytań: każdy klucz ma przypisany limit dobowy oraz limit na minutę. Po przekroczeniu otrzymasz status 429. Konkretne wartości ustalamy indywidualnie przy wydaniu klucza.

Gotowy, żeby zacząć?

Napisz do nas z krótkim opisem swojego projektu, a wyślemy Ci klucz API i wartości limitów. Dostęp jest bezpłatny dla zastosowań niekomercyjnych.

Poproś o dostęp do API

Jak liczymy wynik zaufania Kontakt Sprawdź numer