Platforma dla programistów

Temp Number API - numery telefonów, SMS i OTP

Pozyskuj wirtualne numery telefonów, odbieraj SMS-y w czasie rzeczywistym i automatyzuj weryfikację OTP - przez przejrzyste REST API lub bezpośrednio z asystenta AI.

REST · JSON MCP dla agentów AI cURL · Node.js · Python · PHP
BAZOWY URL https://api.temp-number.com/v1

Strona główna / Dla programistów

Wprowadzenie

Temp Number API opiera się na przewidywalnych zasobach, używa standardowych metod HTTP i zwraca JSON w każdej odpowiedzi. Jeden klucz daje dostęp do odczytu i zapisu wyłącznie w obrębie Twojego konta - nie ma dostępu między kontami.

ProtokółHTTPS · JSON
UwierzytelnianieKlucz Bearer
Wersjav1 (stabilna)
Endpointy17 aktywnych

Szybki start

Od zera do kodu weryfikacyjnego. Wybierz język raz - wszystkie przykłady na stronie się dostosują.

  1. Utwórz klucz API

    W sekcji Panel → Dostęp do API utwórz klucz. Jest wyświetlany tylko raz: zapisz go jako zmienną środowiskową TEMP_NUMBER_API_KEY.

  2. Sprawdź saldo

    Każde wywołanie przekazuje klucz w nagłówku Authorization. Zacznij od czegoś nieszkodliwego: salda portfela.

    curl --request GET "https://api.temp-number.com/v1/account" \
      --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
      --header "Accept: application/json"
  3. Wybierz kraj i sprawdź dostępność

    GET /pricing zwraca każdy kraj z dokładną ceną za okres. Następnie potwierdź dostępność w wybranym kraju.

    curl --request GET "https://api.temp-number.com/v1/inventory?country_code=US&duration=oneMonth" \
      --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
      --header "Accept: application/json"
  4. Kup numer

    Wysyłaj nowy Idempotency-Key przy każdym zakupie. Jeśli połączenie zostanie przerwane, ponów z tym samym kluczem: nigdy nie zostaniesz obciążony dwukrotnie. Zachowaj data.id z odpowiedzi.

    curl --request POST "https://api.temp-number.com/v1/numbers/buy" \
      --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
      --header "Accept: application/json" \
      --header "Content-Type: application/json" \
      --header "Idempotency-Key: $(uuidgen)" \
      --data '{"country_code":"US","duration":"oneMonth"}'
  5. Odczytaj SMS

    Odpytuj numer co kilka sekund, aż przyjdzie wiadomość. Otrzymujesz surowy tekst; kod wyodrębniasz po swojej stronie.

    curl --request GET "https://api.temp-number.com/v1/numbers/1482/sms" \
      --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
      --header "Accept: application/json"
  6. Brak SMS-a? Anuluj i odzyskaj środki

    Od 15 do 120 minut po zakupie numer, który nie odebrał żadnego SMS-a, można anulować z pełnym zwrotem do portfela.

    curl --request POST "https://api.temp-number.com/v1/numbers/1482/cancel" \
      --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
      --header "Accept: application/json" \
      --header "Idempotency-Key: $(uuidgen)"

Uwierzytelnianie

Przesyłaj klucz API w standardowym nagłówku Authorization w każdym żądaniu:

http
Authorization: Bearer YOUR_API_KEY
  • Klucze tworzysz w sekcji Dostęp do API. Pełny klucz jest wyświetlany tylko raz, przy jego utworzeniu.
  • Używaj osobnego klucza dla każdej integracji, aby móc unieważnić jeden bez psucia pozostałych. Zmiana hasła unieważnia wszystkie klucze.
  • Brakujący, błędny lub unieważniony klucz zwraca 401. Konto z niezweryfikowanym adresem e-mail lub zawieszone zwraca 403 z code email_unverified lub account_suspended.
  • Klucze REST działają wyłącznie na /v1. Serwer MCP używa własnego logowania lub kluczy MCP - zobacz Serwer MCP.
Traktuj klucz jak hasło. Przechowuj go na serwerze, nigdy na stronie internetowej ani w aplikacji mobilnej. Natychmiast go zmień, jeśli kiedykolwiek trafił do logów, repozytorium lub został komuś udostępniony.

Bazowy URL i wersjonowanie

Wszystkie endpointy znajdują się pod stałym prefiksem /v1:

bazowy URL
https://api.temp-number.com/v1

Zmiany rozszerzające - nowe pola, endpointy lub opcjonalne parametry - wprowadzamy bez zmiany wersji, więc ignoruj nieznane pola. Zmiana niekompatybilna trafiłaby pod /v2; Twoja integracja nigdy nie zostanie przeniesiona bez uprzedzenia. Kontrakt w formie czytelnej maszynowo to specyfikacja OpenAPI.

Żądania i odpowiedzi

  • Wysyłaj treść JSON z nagłówkiem Content-Type: application/json, a w każdym żądaniu dodawaj Accept: application/json.
  • Sukces: { "success": true, "data": …, "meta": {…} }. meta zawiera liczniki, paginację i podsumowania kwot.
  • Błędy: { "success": false, "message": "…", "code": "…" }. Rozgałęziaj logikę według code; komunikat jest przeznaczony dla ludzi. Zobacz Błędy.
  • Czas jest podawany w formacie ISO 8601. Kwoty są w USD z dwoma miejscami po przecinku – zawsze jest to cena, którą płacisz.
  • Niektóre obiekty nadal zawierają starsze nazwy pól na potrzeby istniejących integracji (w dokumentacji oznaczone jako przestarzałe). Nowy kod powinien je ignorować.
Odpowiedzi nigdy nie ujawniają dostawcy źródłowego ani ceny hurtowej. Jedyna widoczna cena to ta pobierana z Twojego portfela - można ją bezpiecznie pokazywać własnym użytkownikom.

Błędy

Błędy używają standardowych kodów statusu HTTP. Błędy biznesowe zawierają stały, czytelny maszynowo code; niektóre zawierają też details z dodatkowym kontekstem.

422 · błąd biznesowy
{
  "success": false,
  "message": "Insufficient wallet balance.",
  "code": "insufficient_funds"
}
422 · błąd walidacji
{
  "message": "The country code field is required.",
  "errors": {
    "country_code": ["The country code field is required."]
  }
}
StatuscodeZnaczenieCo zrobić
400 - Brak nagłówka Idempotency-Key lub ma on zły format przy zakupie, odnowieniu lub anulowaniu. Treść: {"error": "Missing Idempotency-Key header."} Wyślij UUID w Idempotency-Key.
401 - Brak tokenu Bearer, token o złym formacie lub unieważniony klucz. Sprawdź nagłówek Authorization; jeśli klucz został unieważniony, utwórz nowy.
403 email_unverified Konto nie zweryfikowało jeszcze adresu e-mail. Zweryfikuj e-mail na stronie, a następnie spróbuj ponownie.
403 account_suspended Konto jest zawieszone. Skontaktuj się z pomocą techniczną.
403 kyc_required Konto musi zweryfikować tożsamość przed zakupem nowych numerów. Nic nie pobrano; odnowienia nadal działają. Przejdź weryfikację tożsamości w ustawieniach konta, a następnie spróbuj ponownie.
403 - Klucz nie ma dostępu do API (np. klucz MCP) lub GET /receive-sms zapytano o numer z innego konta. Użyj klucza REST API; pytaj tylko o własne numery.
404 - Numer, wiadomość lub kraj nie znajduje się na Twoim koncie albo nie jest teraz w sprzedaży. Id innych kont również zwracają 404. Pobierz listę ponownie przez GET /numbers lub GET /pricing.
404 private_email_closed Prywatna skrzynka jest zamknięta, ponieważ jej numer został anulowany lub zwrócony. Nie ma czego ponawiać.
409 - Idempotency-Key został już użyty z inną treścią albo pierwsze żądanie z nim nadal trwa. Użyj nowego klucza dla nowego żądania; w przypadku trwającego poczekaj i ponów.
422 insufficient_funds Środki w portfelu nie pokrywają ceny. Doładuj portfel i spróbuj ponownie.
422 out_of_stock Rynek wyprzedał się między sprawdzeniem ceny a zakupem. Sprawdź ponownie GET /inventory i wybierz inny okres lub typ.
422 invalid_duration Ten okres nie jest sprzedawany dla tego kraju i typu numeru. Pobierz ponownie GET /pricing/{countryCode}.
422 - Walidacja nie powiodła się (obiekt `errors` wskazuje każde pole) lub reguła odrzuciła akcję, np. anulowanie poza oknem zwrotu. Przeczytaj `message`; popraw żądanie zamiast je ponawiać.
429 - Osiągnięto limit zapytań. Poczekaj zgodnie z nagłówkiem Retry-After, a następnie ponawiaj z wydłużającymi się odstępami.
503 purchases_paused Nowe zakupy są wstrzymane w całej platformie. Nic nie pobrano; odnowienia i anulowania nadal działają. Ponów po czasie z Retry-After (60 s).
5xx - Coś poszło nie tak po naszej stronie. Ponów z TYM SAMYM Idempotency-Key - nigdy nie zostaniesz obciążony dwukrotnie.

Limity zapytań

Limity obowiązują dla każdego klucza, a wywołania związane z płatnościami mają dodatkowo ostrzejszy limit na konto:

DotyczyLimitLiczone
Wszystkie endpointy60 / minna klucz API
Kupuj, odnawiaj, anuluj10 / minna konto, dodatkowo do powyższych
GET /receive-sms60 / minna klucz API
GET /receive-sms30 / minna klucz API i numer telefonu
GET /receive-sms30 / minna adres IP

Po przekroczeniu limitu otrzymasz 429 z nagłówkiem Retry-After (w sekundach). Odczekaj co najmniej tyle, a następnie ponawiaj z rosnącym opóźnieniem i losowym rozrzutem (jitter). Odpowiedzi zawierają też X-RateLimit-Limit i X-RateLimit-Remaining.

Czekasz na SMS? Odpytuj jeden numer najwyżej co 5 sekund.

Idempotentność

POST /numbers/buy, /renew i /cancel wymagają nagłówka Idempotency-Key: UUID tworzonego dla każdej nowej operacji. Jeśli połączenie zostanie przerwane, wyślij to samo żądanie z tym samym kluczem - otrzymasz pierwotną odpowiedź (oznaczoną X-Idempotency-Replayed: true), a opłata nigdy nie zostanie pobrana dwa razy.

  • Brak klucza: 400. Klucz może mieć do 128 znaków: litery, cyfry, - _ . :
  • Ten sam klucz z inną treścią: 409. Ten sam klucz, gdy pierwsze żądanie wciąż trwa: 409 - odczekaj chwilę i ponów próbę.
  • Klucze są zapamiętywane dla każdego konta i endpointu. Nigdy nie używaj tego samego klucza do innego zakupu.

Paginacja

GET /receive-sms używa paginacji kursorowej, od najnowszych. Sprawdzaj meta.hasMore; dopóki ma wartość true, odsyłaj meta.nextCursor jako cursor z tym samym phoneNumber. Kursory są nieprzezroczyste - nie twórz ich ani nie modyfikuj.

następna strona
GET https://api.temp-number.com/v1/receive-sms?phoneNumber=%2B14035551234&limit=50&cursor=eyJkYXRlIjoiMjAyNi0wNS0xMyJ9

Listy z natury niewielkie (/numbers, /pricing) zwracają wszystko w jednej odpowiedzi; prywatna skrzynka używa page i per_page.

Dozwolone użycie

API jest stworzone dla programistów: procesy weryfikacji i OTP, automatyczny onboarding, testy QA i systemowe oraz każdy produkt, który potrzebuje przychodzących SMS-ów lub numerów telefonów na dużą skalę.

  • Używaj go wyłącznie do uczciwej weryfikacji, programowania i testów.
  • Żadnych oszustw, spamu ani wprowadzania w błąd. Użycie numerów do oszustw lub innych nadużyć skutkuje natychmiastową blokadą konta bez uprzedzenia, anulowaniem powiązanych numerów i brakiem prawa do zwrotu.
  • Nie do kont regulowanych ani powiązanych z tożsamością. Nasze współdzielone, tymczasowe numery nie obsługują weryfikacji SMS w bankowości, płatnościach, kryptowalutach, usługach administracji publicznej ani innych usługach weryfikujących tożsamość prawną (KYC/AML) - do nich używaj własnego, osobistego numeru komórkowego.
Monitorujemy nadużycia. Pełne warunki znajdziesz w Regulaminie.

Dokumentacja API

Wszystkie aktywne endpointy /v1. Żądania po prawej w wybranym języku; odpowiedzi mają rzeczywistą strukturę.

Konto

Odczytaj saldo portfela i walutę rozliczeniową.

GET /v1/account

Pobierz saldo konta

Zwraca dostępne saldo portfela i jego walutę. Sprawdź je przed zakupem, aby wcześniej przerwać z jasnym komunikatem "doładuj".

Pola odpowiedzi
  • balancenumber

    Dostępne saldo portfela.

  • currencystring

    Waluta rozliczeniowa, USD.

Błędy
  • 401Brak klucza lub nieprawidłowy klucz.
curl --request GET "https://api.temp-number.com/v1/account" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
Odpowiedź
{
  "success": true,
  "balance": 124.50,
  "currency": "USD"
}

Ceny i dostępność

Przeglądaj aktywne rynki, dokładną cenę za każdy okres i dostępność w czasie rzeczywistym.

Obiekt cen kraju

Jeden kraj i wszystkie pakiety, które można tam kupić. price to ostateczna kwota pobierana z portfela; koszt u dostawcy nigdy nie jest ujawniany.

Pola
  • country_codestring

    Kod ISO 3166-1 alpha-2, np. US.

  • country_namestring

    Nazwa wyświetlana.

  • packages[].number_typeenum

    voip lub non_voip.

  • packages[].durationenum

    Klucz wysyłany przy zakupie: halfDay, oneDay, oneWeek, oneMonth, threeMonths, sixMonths lub oneYear. Każdy kraj oferuje własny zestaw.

  • packages[].duration_labelstring

    Etykieta czytelna dla człowieka, np. "1 Month".

  • packages[].pricenumber

    Cena końcowa w USD.

  • packages[].original_pricenumber | null

    Cena przed rabatem, jeśli ma zastosowanie.

  • packages[].updated_atnull

    Zarezerwowane.

obiekt
{
  "country_code": "US",
  "country_name": "United States",
  "packages": [
    {
      "number_type": "voip",
      "duration": "oneMonth",
      "duration_label": "1 Month",
      "price": 4.99,
      "original_price": 5.99,
      "updated_at": null
    }
  ]
}
GET /v1/pricing

Lista cen dla wszystkich krajów

Pełny katalog na żywo: lista obiektów cen krajów. Pole price to ostateczna stawka dla użytkownika w USD, dokładnie tyle, ile pobiera się z portfela.

Zwraca

Lista obiektów cen krajów w data, z meta.count.

Błędy
  • 401Brak klucza lub nieprawidłowy klucz.
curl --request GET "https://api.temp-number.com/v1/pricing" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
Odpowiedź
{
  "success": true,
  "data": [
    {
      "country_code": "US",
      "country_name": "United States",
      "packages": [
        {
          "number_type": "voip",
          "duration": "oneMonth",
          "duration_label": "1 Month",
          "price": 4.99,
          "original_price": 5.99,
          "updated_at": null
        },
        {
          "number_type": "voip",
          "duration": "threeMonths",
          "duration_label": "3 Months",
          "price": 12.99,
          "original_price": null,
          "updated_at": null
        }
      ]
    }
  ],
  "meta": { "count": 1 }
}
GET /v1/pricing/{countryCode}

Pobierz ceny dla jednego kraju

Ceny na żywo dla jednego kraju. 404 oznacza, że kraj nie ma teraz aktywnej trasy: traktuj to jako tymczasowy "brak w magazynie", a nie "nigdy w sprzedaży".

Parametry
  • countryCode string path Wymagane

    Kod kraju ISO 3166-1 alpha-2, np. US, GB, CA.

Zwraca

Jeden obiekt cen kraju w data.

Błędy
  • 404Brak aktywnej trasy dla tego kraju w tej chwili.
curl --request GET "https://api.temp-number.com/v1/pricing/GB" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
Odpowiedź
{
  "success": true,
  "data": {
    "country_code": "GB",
    "country_name": "United Kingdom",
    "packages": [
      {
        "number_type": "voip",
        "duration": "oneMonth",
        "duration_label": "1 Month",
        "price": 5.49,
        "original_price": null,
        "updated_at": null
      }
    ]
  }
}
GET /v1/inventory

Sprawdź dostępność

Dostępność w czasie rzeczywistym dla kraju i okresu, dzięki czemu możesz wyłączyć przycisk Kup, zanim ktokolwiek go kliknie. Pomiń number_type, aby otrzymać wszystkie typy obok siebie w types[]. Zielony wynik to mocny sygnał, ale ostatecznym sprawdzeniem jest sam zakup.

Parametry
  • country_code string query Wymagane

    Kod kraju ISO 3166-1 alpha-2.

  • duration enum query Opcjonalnie

    Klucz okresu z GET /pricing/{countryCode}. Pomiń, aby użyć domyślnego dla trasy.

    Jedno z halfDayoneDayoneWeekoneMonththreeMonthssixMonthsoneYear
  • number_type enum query Opcjonalnie

    Ogranicz sprawdzenie do jednego typu. Pomiń, aby zobaczyć wszystkie typy.

    Jedno z voipnon_voip
Pola odpowiedzi
  • stockinteger | null

    Dostępne numery (suma z types[], gdy pominięto number_type).

  • availableboolean

    true, gdy można kupić co najmniej jeden numer.

  • statusstring

    Etykieta czytelna dla człowieka: In Stock, Out of Stock, Coming Soon…

  • types[]array

    Tylko gdy pominięto number_type: number_type, stock, available, status dla każdego typu sprzedawanego na rynku.

Błędy
  • 422Nic nie jest w sprzedaży dla tego wyboru; details zawiera pola dostępności.
curl --request GET "https://api.temp-number.com/v1/inventory?country_code=US&duration=oneMonth" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
Odpowiedź
{
  "success": true,
  "data": {
    "country_code": "US",
    "duration": "oneMonth",
    "number_type": null,
    "stock": 47,
    "available": true,
    "status": "In Stock",
    "types": [
      { "number_type": "voip", "stock": 0, "available": false, "status": "Out of Stock" },
      { "number_type": "non_voip", "stock": 47, "available": true, "status": "In Stock" }
    ]
  }
}

Numery

Wyświetlaj, kupuj, odnawiaj i anuluj prywatne numery. Wywołania przenoszące środki są idempotentne i bezpieczne przy powtórzeniach.

Obiekt numeru

Numer na Twoim koncie. Zakup, odnowienie i anulowanie zwracają też podsumowanie finansowe w meta: charged (lub refunded), currency i wallet_balance_after.

Pola
  • idinteger

    Używaj go w wywołaniach /numbers/{id}/…. Webhooki wysyłają go jako number.rentalId.

  • phone_numberstring

    E.164, np. +14035551234.

  • country_codestring | null

    ISO 3166-1 alpha-2.

  • country_namestring

    Nazwa wyświetlana.

  • number_typeenum

    voip lub non_voip.

  • statusenum

    active, expired, cancelled lub refunded.

  • purchase_datestring

    ISO 8601, UTC.

  • expire_datestring

    ISO 8601, UTC. Po tym czasie numer przestaje odbierać SMS-y i nie można go odnowić.

Przestarzałe aliasy nadal wysyłane dla starszych integracji: country, provider, purchased_at i expires_at (milisekundy epoki). Nie opieraj się na nich.

obiekt
{
  "id": 1482,
  "phone_number": "+14035551234",
  "country_code": "US",
  "country_name": "United States",
  "number_type": "voip",
  "status": "active",
  "purchase_date": "2026-05-13T17:42:09Z",
  "expire_date": "2026-06-13T17:42:09Z"
}
GET /v1/numbers

Lista Twoich numerów

Wszystkie numery na Twoim koncie, od najnowszych. Użyj status=expiring_soon (aktywne numery, którym zostało do 10 dni do wygaśnięcia), aby wysyłać przypomnienia o odnowieniu.

Parametry
  • status enum query Opcjonalnie

    Filtr cyklu życia. Domyślnie all.

    Jedno z allactiveexpiring_soonexpiredcancelled
Zwraca

Lista obiektów numerów w data; meta.count i meta.status.

Błędy
  • 401Brak klucza lub nieprawidłowy klucz.
curl --request GET "https://api.temp-number.com/v1/numbers?status=expiring_soon" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
Odpowiedź
{
  "success": true,
  "data": [
    {
      "id": 1482,
      "phone_number": "+14035551234",
      "country_code": "US",
      "country_name": "United States",
      "number_type": "voip",
      "status": "active",
      "purchase_date": "2026-05-13T17:42:09Z",
      "expire_date": "2026-06-13T17:42:09Z"
    }
  ],
  "meta": { "count": 1, "status": "expiring_soon" }
}
POST /v1/numbers/buy Wymagany Idempotency-Key

Kup numer

Przydziela nowy prywatny numer i obciąża portfel w jednym atomowym kroku. Jeśli realizacja nie powiedzie się po pobraniu opłaty, opłata zostaje cofnięta: nigdy nie zostaniesz z opłatą bez numeru. Odpowiedź pokazuje pobraną kwotę i saldo po operacji.

Parametry
  • country_code string body Wymagane

    Kraj z GET /pricing.

  • duration enum body Wymagane

    Klucz okresu z packages[] danego kraju - każdy kraj oferuje własny zestaw.

    Jedno z halfDayoneDayoneWeekoneMonththreeMonthssixMonthsoneYear
  • number_type enum body Opcjonalnie

    Pomiń, aby użyć domyślnego dla trasy.

    Jedno z voipnon_voip
  • Idempotency-Key string header Wymagane

    UUID, nowy dla każdego zakupu, używany ponownie przy ponowieniach.

Zwraca

Nowy obiekt numeru w data; meta.charged, meta.currency, meta.wallet_balance_after.

Błędy
  • 422insufficient_fundsŚrodki w portfelu nie pokrywają ceny.
  • 422out_of_stockWyprzedane od czasu sprawdzenia dostępności.
  • 422invalid_durationTen okres nie jest sprzedawany dla tego kraju/typu.
  • 403kyc_requiredNajpierw wymagana jest weryfikacja tożsamości. Nic nie pobrano.
  • 503purchases_pausedZakupy wstrzymane w całej platformie. Retry-After: 60.
curl --request POST "https://api.temp-number.com/v1/numbers/buy" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $(uuidgen)" \
  --data '{"country_code":"US","duration":"oneMonth","number_type":"voip"}'
Odpowiedź
{
  "success": true,
  "data": {
    "id": 1482,
    "phone_number": "+14035551234",
    "country_code": "US",
    "country_name": "United States",
    "number_type": "voip",
    "status": "active",
    "purchase_date": "2026-05-13T17:42:09Z",
    "expire_date": "2026-06-13T17:42:09Z"
  },
  "meta": {
    "charged": 4.99,
    "currency": "USD",
    "wallet_balance_after": 119.51
  }
}
POST /v1/numbers/{id}/renew Wymagany Idempotency-Key

Odnów numer

Przedłuża numer o wybrany pakiet. Nowy okres jest dodawany do obecnej daty wygaśnięcia, więc wcześniejsze odnowienie nic nie traci. Cena to aktualna stawka w serwisie, wyliczana po naszej stronie. Wygasłych numerów nie można odnowić: kup nowy.

Parametry
  • id integer path Wymagane

    Id numeru z GET /numbers.

  • package enum body Opcjonalnie

    Długość odnowienia. Domyślnie oneMonth. (duration jest akceptowane jako starszy alias.)

    Jedno z oneMonththreeMonthssixMonthsoneYear
  • Idempotency-Key string header Wymagane

    UUID, nowy dla każdego odnowienia, używany ponownie przy ponowieniach.

Zwraca

Zaktualizowany obiekt numeru w data; meta.charged, meta.currency, meta.wallet_balance_after.

Błędy
  • 404To nie jest numer na Twoim koncie.
  • 422insufficient_fundsŚrodki w portfelu nie pokrywają odnowienia.
  • 422Wygasły, anulowany lub nieodnawialny.
curl --request POST "https://api.temp-number.com/v1/numbers/1482/renew" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $(uuidgen)" \
  --data '{"package":"threeMonths"}'
Odpowiedź
{
  "success": true,
  "data": {
    "id": 1482,
    "phone_number": "+14035551234",
    "country_code": "US",
    "country_name": "United States",
    "number_type": "voip",
    "status": "active",
    "purchase_date": "2026-05-13T17:42:09Z",
    "expire_date": "2026-09-13T17:42:09Z"
  },
  "meta": {
    "charged": 12.99,
    "currency": "USD",
    "wallet_balance_after": 106.52
  }
}
POST /v1/numbers/{id}/cancel Wymagany Idempotency-Key

Anuluj numer i odzyskaj środki

Zwalnia numer i zwraca pełną cenę do portfela. Dozwolone tylko od 15 do 120 minut po zakupie, gdy numer jest aktywny i nie odebrał jeszcze żadnego SMS-a. Poza tymi zasadami wywołanie jest odrzucane z kodem 422 i nic się nie zmienia; jeśli jest za wcześnie, details.seconds_until_open mówi, ile trzeba poczekać.

Parametry
  • id integer path Wymagane

    Id numeru z GET /numbers.

  • Idempotency-Key string header Wymagane

    UUID, używany ponownie przy ponowieniach.

Zwraca

Obiekt numeru (status cancelled) w data; meta.refunded, meta.currency, meta.wallet_balance_after.

Błędy
  • 404To nie jest numer na Twoim koncie.
  • 422Za wcześnie (poniżej 15 min), za późno (powyżej 120 min), numer odebrał już SMS lub nie jest aktywny.
curl --request POST "https://api.temp-number.com/v1/numbers/1482/cancel" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json" \
  --header "Idempotency-Key: $(uuidgen)"
Odpowiedź
{
  "success": true,
  "data": {
    "id": 1482,
    "phone_number": "+14035551234",
    "country_code": "US",
    "country_name": "United States",
    "number_type": "voip",
    "status": "cancelled",
    "purchase_date": "2026-05-13T17:42:09Z",
    "expire_date": "2026-06-13T17:42:09Z"
  },
  "meta": {
    "refunded": 4.99,
    "currency": "USD",
    "wallet_balance_after": 124.50
  }
}

SMS

Odczytuj SMS-y odbierane przez Twoje numery. Otrzymujesz surowy tekst; wyodrębnienie kodu należy do Ciebie.

Obiekt wiadomości SMS

Jeden odebrany SMS, w formie zwracanej przez GET /numbers/{id}/sms. (GET /receive-sms używa wariantu camelCase, pokazanego przy tym endpoincie.)

Pola
  • idinteger

    Id wiadomości.

  • fromstring

    Nadawca: numer telefonu lub nazwa, np. WhatsApp.

  • bodystring

    Pełny tekst wiadomości.

  • received_atstring

    ISO 8601, UTC.

Przestarzałe aliasy nadal wysyłane: sender (= from) i message (= body).

obiekt
{
  "id": 9912,
  "from": "+18005550199",
  "body": "Your code is 432901",
  "received_at": "2026-05-13T17:43:14Z"
}
GET /v1/numbers/{id}/sms

Pobierz numer i jego SMS-y

Jeden numer wraz ze wszystkimi odebranymi SMS-ami, od najnowszych. Najlepsze do widoku szczegółów numeru i do odpytywania pojedynczego numeru, gdy czekasz na kod. Id, które nie należą do Ciebie, zwracają 404.

Parametry
  • id integer path Wymagane

    Id numeru z GET /numbers.

Zwraca

data.number (obiekt numeru) i data.messages (obiekty wiadomości SMS); meta.count.

Błędy
  • 404To nie jest numer na Twoim koncie.
curl --request GET "https://api.temp-number.com/v1/numbers/1482/sms" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
Odpowiedź
{
  "success": true,
  "data": {
    "number": {
      "id": 1482,
      "phone_number": "+14035551234",
      "country_code": "US",
      "country_name": "United States",
      "number_type": "voip",
      "status": "active",
      "purchase_date": "2026-05-13T17:42:09Z",
      "expire_date": "2026-06-13T17:42:09Z"
    },
    "messages": [
      {
        "id": 9912,
        "from": "+18005550199",
        "body": "Your code is 432901",
        "received_at": "2026-05-13T17:43:14Z"
      }
    ]
  },
  "meta": { "count": 1 }
}
GET /v1/receive-sms

Odbieranie SMS-ów po numerze telefonu

SMS-y z paginacją kursorową dla Twojego numeru, wskazywanego numerem telefonu zamiast id. Najlepsze dla skrzynek o dużym ruchu. Numer, który nie należy do Ciebie, zwraca 403.

Parametry
  • phoneNumber string query Wymagane

    E.164 lub same cyfry, np. +14035551234. Zakoduj + w URL.

  • limit integer query Opcjonalnie

    Rozmiar strony 1-100. Domyślnie 50.

  • cursor string query Opcjonalnie

    meta.nextCursor z poprzedniej strony.

Pola odpowiedzi
  • data.messages[].idinteger

    Id wiadomości.

  • data.messages[].fromstring

    Nadawca.

  • data.messages[].tostring

    Twój numer.

  • data.messages[].messagestring

    Pełny tekst.

  • data.messages[].receivedAtstring

    ISO 8601.

  • meta.hasMore / nextCursorboolean / string | null

    Przekaż nextCursor jako cursor, aby pobrać następną stronę.

Błędy
  • 403Numer nie znajduje się na Twoim koncie.
  • 422Brak phoneNumber lub jest nieprawidłowy.
curl --request GET "https://api.temp-number.com/v1/receive-sms?phoneNumber=%2B14035551234&limit=50" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
Odpowiedź
{
  "success": true,
  "data": {
    "phoneNumber": "+14035551234",
    "purchaseStatus": "active",
    "messages": [
      {
        "id": 1842,
        "from": "WhatsApp",
        "to": "+14035551234",
        "message": "Your verification code is 483920.",
        "receivedAt": "2026-05-13T17:43:14+00:00"
      }
    ]
  },
  "meta": {
    "count": 1,
    "pageSize": 50,
    "hasMore": false,
    "nextCursor": null,
    "prevCursor": null,
    "requestedAt": "2026-05-13T17:43:20+00:00"
  }
}

Prywatny e-mail

Darmowa skrzynka [email protected] tylko do odbioru dla każdego prywatnego numeru. Jeden adres na numer.

Obiekt prywatnego e-maila

Skrzynka przypisana do jednego numeru.

Pola
  • addressstring | null

    Adres lub null przed aktywacją.

  • statusenum

    active lub none.

  • unread_countinteger

    Nieprzeczytane e-maile.

  • created_atstring | null

    Kiedy adres został aktywowany.

  • eligibleboolean

    true, gdy numer może teraz aktywować adres.

  • linked_numberstring

    Numer telefonu, do którego należy.

  • domainstring

    privnum.com

  • suggestionsstring[]

    Propozycje nazw, gdy numer się kwalifikuje.

obiekt
{
  "address": "[email protected]",
  "status": "active",
  "unread_count": 2,
  "created_at": "2026-07-03T10:15:00+00:00",
  "eligible": false,
  "linked_number": "+14035551234",
  "domain": "privnum.com",
  "suggestions": []
}
GET /v1/numbers/{id}/private-email

Pobierz prywatny e-mail

Adres numeru lub, zanim zostanie aktywowany, informacja, czy numer może go mieć, oraz kilka propozycji nazw.

Parametry
  • id integer path Wymagane

    Id numeru z GET /numbers.

Zwraca

Obiekt prywatnego e-maila w data.

Błędy
  • 404To nie jest numer na Twoim koncie.
curl --request GET "https://api.temp-number.com/v1/numbers/1482/private-email" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
Odpowiedź
{
  "success": true,
  "data": {
    "address": null,
    "status": "none",
    "unread_count": 0,
    "created_at": null,
    "eligible": true,
    "linked_number": "+14035551234",
    "domain": "privnum.com",
    "suggestions": ["alex.smith", "alex.smith42"]
  }
}
GET /v1/numbers/{id}/private-email/availability

Sprawdź nazwę

Sprawdzenie na żywo, czy nazwa jest prawidłowa i wolna, zanim ją aktywujesz.

Parametry
  • id integer path Wymagane

    Id numeru z GET /numbers.

  • local_part string query Wymagane

    Część przed @: 3-64 litery, cyfry, kropki, myślniki lub podkreślenia.

Pola odpowiedzi
  • availableboolean

    true, gdy możesz go aktywować.

  • reasonenum | null

    too_short, too_long, invalid, reserved lub taken.

Błędy
  • 404To nie jest numer na Twoim koncie.
curl --request GET "https://api.temp-number.com/v1/numbers/1482/private-email/availability?local_part=alex.smith" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
Odpowiedź
{
  "success": true,
  "data": {
    "local_part": "alex.smith",
    "address": "[email protected]",
    "available": true,
    "reason": null,
    "message": "Available"
  }
}
POST /v1/numbers/{id}/private-email

Aktywuj adres

Przypisuje aktywnemu numerowi jego adres. Bezpłatnie, jeden na numer, a aktywowany adres nigdy nie zostanie przekazany nikomu innemu.

Parametry
  • id integer path Wymagane

    Id numeru z GET /numbers.

  • local_part string body Wymagane

    Sprawdzana nazwa.

Zwraca

Obiekt prywatnego e-maila w data.

Błędy
  • 404Nie Twój numer albo nie ma jeszcze adresu.
  • 422Nazwa zajęta lub nieprawidłowa (details.reason), numer ma już adres albo nie jest aktywny.
curl --request POST "https://api.temp-number.com/v1/numbers/1482/private-email" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{"local_part":"alex.smith"}'
Odpowiedź
{
  "success": true,
  "data": {
    "address": "[email protected]",
    "status": "active",
    "unread_count": 0,
    "created_at": "2026-07-03T10:15:00+00:00",
    "eligible": false,
    "linked_number": "+14035551234",
    "domain": "privnum.com",
    "suggestions": []
  }
}
GET /v1/numbers/{id}/private-email/inbox

Lista e-maili

Podsumowania e-maili, od najnowszych, z paginacją stronicową i liczbą nieprzeczytanych na najwyższym poziomie.

Parametry
  • id integer path Wymagane

    Id numeru z GET /numbers.

  • page integer query Opcjonalnie

    Numer strony. Domyślnie 1.

  • per_page integer query Opcjonalnie

    1-100. Domyślnie 25.

Pola odpowiedzi
  • data[]array

    id, from_email, from_name, subject, preview, attachment_count, is_read, received_at.

  • metaobject

    current_page, per_page, total, last_page.

  • unread_countinteger

    Najwyższy poziom, obok data.

Błędy
  • 404Nie Twój numer albo nie ma jeszcze adresu.
  • 404private_email_closedNumer został anulowany lub zwrócony.
curl --request GET "https://api.temp-number.com/v1/numbers/1482/private-email/inbox?page=1&per_page=25" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
Odpowiedź
{
  "success": true,
  "data": [
    {
      "id": 77,
      "from_email": "[email protected]",
      "from_name": "Example Billing",
      "subject": "Your receipt",
      "preview": "Thanks for your order…",
      "attachment_count": 1,
      "is_read": false,
      "received_at": "2026-07-04T08:01:12+00:00"
    }
  ],
  "meta": { "current_page": 1, "per_page": 25, "total": 1, "last_page": 1 },
  "unread_count": 1
}
GET /v1/numbers/{id}/private-email/inbox/{messageId}/body

Odczytaj e-mail

Pełny e-mail (HTML i tekst) z listą załączników. Odczytanie oznacza go jako przeczytany.

Parametry
  • id integer path Wymagane

    Id numeru z GET /numbers.

  • messageId integer path Wymagane

    Id e-maila z listy skrzynki.

Błędy
  • 404Nie Twój numer albo nie ma jeszcze adresu.
  • 404private_email_closedNumer został anulowany lub zwrócony.
curl --request GET "https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77/body" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
Odpowiedź
{
  "success": true,
  "data": {
    "id": 77,
    "subject": "Your receipt",
    "from_email": "[email protected]",
    "from_name": "Example Billing",
    "received_at": "2026-07-04T08:01:12+00:00",
    "html": "<p>Thanks for your order…</p>",
    "text": "Thanks for your order…",
    "attachments": [
      { "index": 0, "filename": "receipt.pdf", "content_type": "application/pdf", "size_bytes": 48211 }
    ]
  }
}
GET /v1/numbers/{id}/private-email/inbox/{messageId}/attachments/{index}

Pobierz załącznik

Surowy plik z własnym Content-Type i nazwą pliku. index pochodzi z attachments[] e-maila.

Parametry
  • id integer path Wymagane

    Id numeru z GET /numbers.

  • messageId integer path Wymagane

    Id e-maila z listy skrzynki.

  • index integer path Wymagane

    attachments[].index z „Odczytaj e-mail”.

Błędy
  • 404Nie Twój numer albo nie ma jeszcze adresu.
  • 404private_email_closedNumer został anulowany lub zwrócony.
  • 404Brak załącznika o tym indeksie.
curl --request GET "https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77/attachments/0" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --output receipt.pdf
Odpowiedź
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename=receipt.pdf

<binary file>
DELETE /v1/numbers/{id}/private-email/inbox/{messageId}

Usuń e-mail

Usuwa e-mail i jego załączniki.

Parametry
  • id integer path Wymagane

    Id numeru z GET /numbers.

  • messageId integer path Wymagane

    Id e-maila z listy skrzynki.

Błędy
  • 404Nie Twój numer albo nie ma jeszcze adresu.
  • 404private_email_closedNumer został anulowany lub zwrócony.
curl --request DELETE "https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
Odpowiedź
{
  "success": true,
  "data": null
}

AI i MCP

Pozwól asystentowi AI korzystać bezpośrednio z Twojego konta albo daj agentowi programistycznemu wszystko, czego potrzebuje do pracy z API.

Serwer MCP

Oprócz REST API udostępniamy serwer Model Context Protocol. Podłącz go do Claude, ChatGPT lub swojego edytora, a asystent sprawdzi ceny i dostępność, kupi numer i odczyta jego SMS-y jako natywne narzędzia – bez pisania kodu. Nie znasz MCP? Zacznij od przeglądu serwera MCP.

Endpoint
Endpoint MCP · streamable HTTP
https://mcp.temp-number.com/mcp

Jak działa logowanie

  • Dodaj URL do swojej aplikacji AI. Przekieruje Cię do Temp Number, gdzie zalogujesz się własnym kontem (OAuth 2.1 z PKCE) – bez kopiowania klucza.
  • Na ekranie zgody wybierasz, co asystent może robić. Odczyt salda, cen, Twoich numerów i ich SMS-ów jest zawsze włączony. Zezwól na zakupy – kupowanie, odnawianie i anulowanie z użyciem portfela – jest wyłączone, dopóki go nie zaznaczysz.
  • Każde połączenie jest widoczne w Panel → Serwer MCP → Połączone aplikacje, gdzie możesz je w każdej chwili rozłączyć.
  • Wolisz klucz (CI, skrypty, agenci bez interfejsu)? Utwórz klucz MCP na tej samej stronie i wysyłaj go jako Authorization: Bearer <key>. Klucze MCP i klucze REST API nie są wymienne.

Narzędzia

NarzędzieCo robiWymaga „Zezwól na zakupy”
get-balancePobierz saldo portfela i walutę rozliczeń uwierzytelnionego konta.Nie
get-pricingZwróć aktywny cennik dla wszystkich krajów lub jednego kodu kraju ISO.Nie
get-inventorySprawdź bieżącą dostępność numerów dla kraju, okresu i opcjonalnie typu numeru.Nie
purchase-numberKup jeden prywatny numer dla uwierzytelnionego konta ze środków w portfelu.Tak
list-active-numbersZwróć numery należące do uwierzytelnionego konta, opcjonalnie filtrowane według statusu.Nie
check-smsPobierz wiadomości SMS dla ID kupionego numeru należącego do uwierzytelnionego konta.Nie
renew-numberOdnów kupiony numer po ID, opcjonalnie wybierając pakiet okresu.Tak
cancel-numberAnuluj kupiony numer po ID i zwróć do portfela przysługujące środki.Tak

Podłącz swoje narzędzie AI

Wybierz swoją aplikację. Większość łączy się jednym kliknięciem: logujesz się do Temp Number, zaznaczasz, co asystent może robić, i klikasz Zezwól.

Claude – claude.ai, aplikacja desktopowa i mobilna

Nic do instalowania. Działa w przeglądarce, w aplikacji desktopowej i na urządzeniach mobilnych.

  1. Kliknij Dodaj do Claude. Claude otworzy się z już uzupełnioną nazwą Temp Number i jej URL. Kliknij Add.
  2. Kliknij Connect, zaloguj się do Temp Number, wybierz, czy Claude może dokonywać zakupów, i kliknij Zezwól.
  3. W dowolnym czacie otwórz menu + → Connectors i włącz Temp Number. Spróbuj: „Ile kosztuje numer z USA na miesiąc?”
Team i Enterprise: właściciel dodaje connector raz w Ustawieniach organizacji → Connectors. Każdy członek loguje się potem własnym kontem Temp Number, więc każdy płaci z własnego portfela.

Brak przycisku? W Claude przejdź do Customize → Connectors → Add custom connector i wklej endpoint MCP. Organizacje z opcją nagłówków żądań w Claude mogą zamiast logowania wysyłać klucz MCP jako Authorization: Bearer <key>.

llms.txt i prompt dla agenta

Budujesz z asystentem AI do kodowania? Przekaż mu poniższy kontekst, a poprawnie zintegruje API za jednym razem – razem z uwierzytelnianiem, idempotencją i limitami zapytań.

llms.txt Specyfikacja OpenAPI
prompt.md
You are integrating the Temp Number REST API. Read the full, machine-readable reference before writing any code:

- API reference (llms.txt): https://temp-number.com/developers/llms.txt
- OpenAPI spec: https://api.temp-number.com/api.json
- Base URL: https://api.temp-number.com/v1
- MCP server (for AI agents that call tools directly): https://mcp.temp-number.com/mcp - sign in with OAuth, or send an MCP key as a Bearer token.

Rules: authenticate every request with `Authorization: Bearer <YOUR_API_KEY>` (created in the dashboard → API Access) and keep the key in an environment variable, never in code; send and accept JSON over HTTPS; send a unique `Idempotency-Key` (UUID) header on every POST that buys, renews or cancels - it is required, and retries must reuse the same key; branch on the `code` field of error responses, not on the message text; on HTTP 429 or 503, wait for the `Retry-After` header. All prices are final USD.

Task: <describe what you want to build - e.g. "buy a US number, wait for the verification SMS, then cancel it if it never arrives">.
https://temp-number.com/developers/llms.txt to zawsze aktualne, tekstowe podsumowanie wszystkich endpointów; specyfikacja OpenAPI to typowany kontrakt. Oba aktualizują się razem z API.

Zasoby

Co się zmieniło i gdzie uzyskać pomoc.

Lista zmian

Wyłącznie zmiany rozszerzające - nic z /v1 nie zostało usunięte.

  • NewMCP: zaloguj się kontem Temp Number

    "Dodaj do Claude" jednym kliknięciem, a także ChatGPT, Claude Code, Codex, Cursor i VS Code bez kopiowania klucza. Na ekranie zgody decydujesz, czy AI może wydawać środki.

  • DocsNowe miejsce dla dokumentacji

    Szybki start, wyszukiwarka i każdy przykład w cURL, Node.js, Python i PHP. Błędy, limity zapytań i zwroty są teraz dokładnie zgodne z działającym API.

  • Newllms.txt dla całej witryny

    Tekstowa mapa serwisu dla asystentów AI, z linkiem do dokumentacji API przygotowanej dla agentów.

  • NewPodłącz swoje narzędzie AI

    Konfiguracja dla Claude Code, Codex, Cursor i VS Code, z linkami do instalacji jednym kliknięciem dla Cursor i VS Code.

  • NewSpecyfikacja OpenAPI

    Kontrakt czytelny maszynowo jest dostępny pod adresem https://api.temp-number.com/api.json.

  • ImprovedObiekty zgodne z dokumentacją

    Numery i SMS-y używają dat ISO 8601 oraz from/body. Błędy zawierają kod czytelny maszynowo (out_of_stock, insufficient_funds, invalid_duration). /inventory zwraca każdy typ numeru, gdy pominiesz number_type. Stare nazwy pól nadal działają jako przestarzałe aliasy.

  • NewEndpointy prywatnego e-maila

    Aktywuj darmową skrzynkę [email protected] dla numeru, czytaj pocztę i pobieraj załączniki przez API.

  • NewSerwer MCP

    Agenci AI mogą sprawdzać ceny, kupować numery i czytać SMS-y jako narzędzia, używając klucza MCP.

  • LaunchPubliczne REST API v1

    Konto, ceny, dostępność, cykl życia numeru i SMS-y, z uwierzytelnianiem tokenem Bearer.

Pomoc

Problem z integracją albo niezgodność między dokumentacją a działaniem API? Skontaktuj się z nami - podaj endpoint, czas żądania i treść odpowiedzi (nigdy nie podawaj klucza API).

Zaczynamy?

Utwórz klucz i wykonaj pierwsze wywołanie w niecałą minutę.

Zaloguj się, aby zacząć