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.
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.
Szybki start
Od zera do kodu weryfikacyjnego. Wybierz język raz - wszystkie przykłady na stronie się dostosują.
-
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. -
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"const response = await fetch("https://api.temp-number.com/v1/account", { headers: { Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`, Accept: "application/json", }, }); const result = await response.json(); console.log(response.status, result);import os import requests response = requests.get( "https://api.temp-number.com/v1/account", headers={ "Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}", "Accept": "application/json", }, timeout=30, ) print(response.status_code, response.json())use Illuminate\Support\Facades\Http; // config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')] $response = Http::withToken(config('services.temp_number.key')) ->acceptJson() ->get('https://api.temp-number.com/v1/account'); $result = $response->json(); -
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"const response = await fetch("https://api.temp-number.com/v1/inventory?country_code=US&duration=oneMonth", { headers: { Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`, Accept: "application/json", }, }); const result = await response.json(); console.log(response.status, result);import os import requests response = requests.get( "https://api.temp-number.com/v1/inventory", headers={ "Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}", "Accept": "application/json", }, params={"country_code": "US", "duration": "oneMonth"}, timeout=30, ) print(response.status_code, response.json())use Illuminate\Support\Facades\Http; // config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')] $response = Http::withToken(config('services.temp_number.key')) ->acceptJson() ->get('https://api.temp-number.com/v1/inventory', [ 'country_code' => 'US', 'duration' => 'oneMonth', ]); $result = $response->json(); -
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"}'import { randomUUID } from "node:crypto"; const response = await fetch("https://api.temp-number.com/v1/numbers/buy", { method: "POST", headers: { Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`, Accept: "application/json", "Content-Type": "application/json", "Idempotency-Key": randomUUID(), }, body: JSON.stringify({ country_code: "US", duration: "oneMonth" }), }); const result = await response.json(); console.log(response.status, result);import os import uuid import requests response = requests.post( "https://api.temp-number.com/v1/numbers/buy", headers={ "Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}", "Accept": "application/json", "Idempotency-Key": str(uuid.uuid4()), }, json={"country_code": "US", "duration": "oneMonth"}, timeout=60, ) print(response.status_code, response.json())use Illuminate\Support\Facades\Http; use Illuminate\Support\Str; // config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')] $response = Http::withToken(config('services.temp_number.key')) ->acceptJson() ->withHeaders(['Idempotency-Key' => (string) Str::uuid()]) ->timeout(60) ->post('https://api.temp-number.com/v1/numbers/buy', [ 'country_code' => 'US', 'duration' => 'oneMonth', ]); $result = $response->json(); -
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"const response = await fetch("https://api.temp-number.com/v1/numbers/1482/sms", { headers: { Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`, Accept: "application/json", }, }); const result = await response.json(); console.log(response.status, result);import os import requests response = requests.get( "https://api.temp-number.com/v1/numbers/1482/sms", headers={ "Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}", "Accept": "application/json", }, timeout=30, ) print(response.status_code, response.json())use Illuminate\Support\Facades\Http; // config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')] $response = Http::withToken(config('services.temp_number.key')) ->acceptJson() ->get('https://api.temp-number.com/v1/numbers/1482/sms'); $result = $response->json(); -
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)"import { randomUUID } from "node:crypto"; const response = await fetch("https://api.temp-number.com/v1/numbers/1482/cancel", { method: "POST", headers: { Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`, Accept: "application/json", "Idempotency-Key": randomUUID(), }, }); const result = await response.json(); console.log(response.status, result);import os import uuid import requests response = requests.post( "https://api.temp-number.com/v1/numbers/1482/cancel", headers={ "Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}", "Accept": "application/json", "Idempotency-Key": str(uuid.uuid4()), }, timeout=60, ) print(response.status_code, response.json())use Illuminate\Support\Facades\Http; use Illuminate\Support\Str; // config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')] $response = Http::withToken(config('services.temp_number.key')) ->acceptJson() ->withHeaders(['Idempotency-Key' => (string) Str::uuid()]) ->timeout(60) ->post('https://api.temp-number.com/v1/numbers/1482/cancel'); $result = $response->json();
Uwierzytelnianie
Przesyłaj klucz API w standardowym nagłówku Authorization w każdym żądaniu:
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 zwraca403zcodeemail_unverifiedlubaccount_suspended. - Klucze REST działają wyłącznie na
/v1. Serwer MCP używa własnego logowania lub kluczy MCP - zobacz Serwer MCP.
Bazowy URL i wersjonowanie
Wszystkie endpointy znajdują się pod stałym prefiksem /v1:
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 dodawajAccept: application/json. - Sukces:
{ "success": true, "data": …, "meta": {…} }.metazawiera liczniki, paginację i podsumowania kwot. - Błędy:
{ "success": false, "message": "…", "code": "…" }. Rozgałęziaj logikę wedługcode; 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ć.
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.
{
"success": false,
"message": "Insufficient wallet balance.",
"code": "insufficient_funds"
}
{
"message": "The country code field is required.",
"errors": {
"country_code": ["The country code field is required."]
}
}
| Status | code | Znaczenie | Co 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:
| Dotyczy | Limit | Liczone |
|---|---|---|
| Wszystkie endpointy | 60 / min | na klucz API |
| Kupuj, odnawiaj, anuluj | 10 / min | na konto, dodatkowo do powyższych |
| GET /receive-sms | 60 / min | na klucz API |
| GET /receive-sms | 30 / min | na klucz API i numer telefonu |
| GET /receive-sms | 30 / min | na 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.
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.
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.
Dokumentacja API
Wszystkie aktywne endpointy /v1. Żądania po prawej w wybranym języku; odpowiedzi mają rzeczywistą strukturę.
Konto
Odczytaj saldo portfela i walutę rozliczeniową.
/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-
balancenumberDostępne saldo portfela.
-
currencystringWaluta rozliczeniowa, USD.
- 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"
const response = await fetch("https://api.temp-number.com/v1/account", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/account",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/account');
$result = $response->json();
{
"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_codestringKod ISO 3166-1 alpha-2, np. US.
-
country_namestringNazwa wyświetlana.
-
packages[].number_typeenumvoip lub non_voip.
-
packages[].durationenumKlucz wysyłany przy zakupie: halfDay, oneDay, oneWeek, oneMonth, threeMonths, sixMonths lub oneYear. Każdy kraj oferuje własny zestaw.
-
packages[].duration_labelstringEtykieta czytelna dla człowieka, np. "1 Month".
-
packages[].pricenumberCena końcowa w USD.
-
packages[].original_pricenumber | nullCena przed rabatem, jeśli ma zastosowanie.
-
packages[].updated_atnullZarezerwowane.
{
"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
}
]
}
/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.
ZwracaLista 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"
const response = await fetch("https://api.temp-number.com/v1/pricing", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/pricing",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/pricing');
$result = $response->json();
{
"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 }
}
/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-
countryCodestring path WymaganeKod kraju ISO 3166-1 alpha-2, np. US, GB, CA.
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"
const response = await fetch("https://api.temp-number.com/v1/pricing/GB", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/pricing/GB",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/pricing/GB');
$result = $response->json();
{
"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
}
]
}
}
/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_codestring query WymaganeKod kraju ISO 3166-1 alpha-2.
-
durationenum query OpcjonalnieKlucz okresu z GET /pricing/{countryCode}. Pomiń, aby użyć domyślnego dla trasy.
Jedno zhalfDayoneDayoneWeekoneMonththreeMonthssixMonthsoneYear -
number_typeenum query OpcjonalnieOgranicz sprawdzenie do jednego typu. Pomiń, aby zobaczyć wszystkie typy.
Jedno zvoipnon_voip
-
stockinteger | nullDostępne numery (suma z types[], gdy pominięto number_type).
-
availablebooleantrue, gdy można kupić co najmniej jeden numer.
-
statusstringEtykieta czytelna dla człowieka: In Stock, Out of Stock, Coming Soon…
-
types[]arrayTylko gdy pominięto number_type: number_type, stock, available, status dla każdego typu sprzedawanego na rynku.
- 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"
const response = await fetch("https://api.temp-number.com/v1/inventory?country_code=US&duration=oneMonth", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/inventory",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
params={"country_code": "US", "duration": "oneMonth"},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/inventory', [
'country_code' => 'US',
'duration' => 'oneMonth',
]);
$result = $response->json();
{
"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-
idintegerUżywaj go w wywołaniach /numbers/{id}/…. Webhooki wysyłają go jako number.rentalId.
-
phone_numberstringE.164, np. +14035551234.
-
country_codestring | nullISO 3166-1 alpha-2.
-
country_namestringNazwa wyświetlana.
-
number_typeenumvoip lub non_voip.
-
statusenumactive, expired, cancelled lub refunded.
-
purchase_datestringISO 8601, UTC.
-
expire_datestringISO 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.
{
"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"
}
/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-
statusenum query OpcjonalnieFiltr cyklu życia. Domyślnie all.
Jedno zallactiveexpiring_soonexpiredcancelled
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"
const response = await fetch("https://api.temp-number.com/v1/numbers?status=expiring_soon", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/numbers",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
params={"status": "expiring_soon"},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/numbers', [
'status' => 'expiring_soon',
]);
$result = $response->json();
{
"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" }
}
/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_codestring body WymaganeKraj z GET /pricing.
-
durationenum body WymaganeKlucz okresu z packages[] danego kraju - każdy kraj oferuje własny zestaw.
Jedno zhalfDayoneDayoneWeekoneMonththreeMonthssixMonthsoneYear -
number_typeenum body OpcjonalniePomiń, aby użyć domyślnego dla trasy.
Jedno zvoipnon_voip -
Idempotency-Keystring header WymaganeUUID, nowy dla każdego zakupu, używany ponownie przy ponowieniach.
Nowy obiekt numeru w data; meta.charged, meta.currency, meta.wallet_balance_after.
Błędy- 422
insufficient_fundsŚrodki w portfelu nie pokrywają ceny. - 422
out_of_stockWyprzedane od czasu sprawdzenia dostępności. - 422
invalid_durationTen okres nie jest sprzedawany dla tego kraju/typu. - 403
kyc_requiredNajpierw wymagana jest weryfikacja tożsamości. Nic nie pobrano. - 503
purchases_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"}'
import { randomUUID } from "node:crypto";
const response = await fetch("https://api.temp-number.com/v1/numbers/buy", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
"Content-Type": "application/json",
"Idempotency-Key": randomUUID(),
},
body: JSON.stringify({ country_code: "US", duration: "oneMonth", number_type: "voip" }),
});
const result = await response.json();
console.log(response.status, result);
import os
import uuid
import requests
response = requests.post(
"https://api.temp-number.com/v1/numbers/buy",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
"Idempotency-Key": str(uuid.uuid4()),
},
json={"country_code": "US", "duration": "oneMonth", "number_type": "voip"},
timeout=60,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Str;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->withHeaders(['Idempotency-Key' => (string) Str::uuid()])
->timeout(60)
->post('https://api.temp-number.com/v1/numbers/buy', [
'country_code' => 'US',
'duration' => 'oneMonth',
'number_type' => 'voip',
]);
$result = $response->json();
{
"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
}
}
/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-
idinteger path WymaganeId numeru z GET /numbers.
-
packageenum body OpcjonalnieDługość odnowienia. Domyślnie oneMonth. (duration jest akceptowane jako starszy alias.)
Jedno zoneMonththreeMonthssixMonthsoneYear -
Idempotency-Keystring header WymaganeUUID, nowy dla każdego odnowienia, używany ponownie przy ponowieniach.
Zaktualizowany obiekt numeru w data; meta.charged, meta.currency, meta.wallet_balance_after.
Błędy- 404To nie jest numer na Twoim koncie.
- 422
insufficient_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"}'
import { randomUUID } from "node:crypto";
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/renew", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
"Content-Type": "application/json",
"Idempotency-Key": randomUUID(),
},
body: JSON.stringify({ package: "threeMonths" }),
});
const result = await response.json();
console.log(response.status, result);
import os
import uuid
import requests
response = requests.post(
"https://api.temp-number.com/v1/numbers/1482/renew",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
"Idempotency-Key": str(uuid.uuid4()),
},
json={"package": "threeMonths"},
timeout=60,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Str;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->withHeaders(['Idempotency-Key' => (string) Str::uuid()])
->timeout(60)
->post('https://api.temp-number.com/v1/numbers/1482/renew', [
'package' => 'threeMonths',
]);
$result = $response->json();
{
"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
}
}
/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-
idinteger path WymaganeId numeru z GET /numbers.
-
Idempotency-Keystring header WymaganeUUID, używany ponownie przy ponowieniach.
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)"
import { randomUUID } from "node:crypto";
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/cancel", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
"Idempotency-Key": randomUUID(),
},
});
const result = await response.json();
console.log(response.status, result);
import os
import uuid
import requests
response = requests.post(
"https://api.temp-number.com/v1/numbers/1482/cancel",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
"Idempotency-Key": str(uuid.uuid4()),
},
timeout=60,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Str;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->withHeaders(['Idempotency-Key' => (string) Str::uuid()])
->timeout(60)
->post('https://api.temp-number.com/v1/numbers/1482/cancel');
$result = $response->json();
{
"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-
idintegerId wiadomości.
-
fromstringNadawca: numer telefonu lub nazwa, np. WhatsApp.
-
bodystringPełny tekst wiadomości.
-
received_atstringISO 8601, UTC.
Przestarzałe aliasy nadal wysyłane: sender (= from) i message (= body).
{
"id": 9912,
"from": "+18005550199",
"body": "Your code is 432901",
"received_at": "2026-05-13T17:43:14Z"
}
/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-
idinteger path WymaganeId numeru z GET /numbers.
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"
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/sms", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/numbers/1482/sms",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/numbers/1482/sms');
$result = $response->json();
{
"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 }
}
/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-
phoneNumberstring query WymaganeE.164 lub same cyfry, np. +14035551234. Zakoduj + w URL.
-
limitinteger query OpcjonalnieRozmiar strony 1-100. Domyślnie 50.
-
cursorstring query Opcjonalniemeta.nextCursor z poprzedniej strony.
-
data.messages[].idintegerId wiadomości.
-
data.messages[].fromstringNadawca.
-
data.messages[].tostringTwój numer.
-
data.messages[].messagestringPełny tekst.
-
data.messages[].receivedAtstringISO 8601.
-
meta.hasMore / nextCursorboolean / string | nullPrzekaż nextCursor jako cursor, aby pobrać następną stronę.
- 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"
const response = await fetch("https://api.temp-number.com/v1/receive-sms?phoneNumber=%2B14035551234&limit=50", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/receive-sms",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
params={"phoneNumber": "+14035551234", "limit": 50},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/receive-sms', [
'phoneNumber' => '+14035551234',
'limit' => 50,
]);
$result = $response->json();
{
"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 | nullAdres lub null przed aktywacją.
-
statusenumactive lub none.
-
unread_countintegerNieprzeczytane e-maile.
-
created_atstring | nullKiedy adres został aktywowany.
-
eligiblebooleantrue, gdy numer może teraz aktywować adres.
-
linked_numberstringNumer telefonu, do którego należy.
-
domainstringprivnum.com
-
suggestionsstring[]Propozycje nazw, gdy numer się kwalifikuje.
{
"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": []
}
/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-
idinteger path WymaganeId numeru z GET /numbers.
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"
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/private-email", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/numbers/1482/private-email",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/numbers/1482/private-email');
$result = $response->json();
{
"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"]
}
}
/v1/numbers/{id}/private-email/availability
Sprawdź nazwę
Sprawdzenie na żywo, czy nazwa jest prawidłowa i wolna, zanim ją aktywujesz.
Parametry-
idinteger path WymaganeId numeru z GET /numbers.
-
local_partstring query WymaganeCzęść przed @: 3-64 litery, cyfry, kropki, myślniki lub podkreślenia.
-
availablebooleantrue, gdy możesz go aktywować.
-
reasonenum | nulltoo_short, too_long, invalid, reserved lub taken.
- 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"
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/private-email/availability?local_part=alex.smith", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/numbers/1482/private-email/availability",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
params={"local_part": "alex.smith"},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/numbers/1482/private-email/availability', [
'local_part' => 'alex.smith',
]);
$result = $response->json();
{
"success": true,
"data": {
"local_part": "alex.smith",
"address": "[email protected]",
"available": true,
"reason": null,
"message": "Available"
}
}
/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-
idinteger path WymaganeId numeru z GET /numbers.
-
local_partstring body WymaganeSprawdzana nazwa.
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"}'
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/private-email", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
"Content-Type": "application/json",
},
body: JSON.stringify({ local_part: "alex.smith" }),
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.post(
"https://api.temp-number.com/v1/numbers/1482/private-email",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
json={"local_part": "alex.smith"},
timeout=60,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->timeout(60)
->post('https://api.temp-number.com/v1/numbers/1482/private-email', [
'local_part' => 'alex.smith',
]);
$result = $response->json();
{
"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": []
}
}
/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-
idinteger path WymaganeId numeru z GET /numbers.
-
pageinteger query OpcjonalnieNumer strony. Domyślnie 1.
-
per_pageinteger query Opcjonalnie1-100. Domyślnie 25.
-
data[]arrayid, from_email, from_name, subject, preview, attachment_count, is_read, received_at.
-
metaobjectcurrent_page, per_page, total, last_page.
-
unread_countintegerNajwyższy poziom, obok data.
- 404Nie Twój numer albo nie ma jeszcze adresu.
- 404
private_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"
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/private-email/inbox?page=1&per_page=25", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/numbers/1482/private-email/inbox",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
params={"page": 1, "per_page": 25},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/numbers/1482/private-email/inbox', [
'page' => 1,
'per_page' => 25,
]);
$result = $response->json();
{
"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
}
/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-
idinteger path WymaganeId numeru z GET /numbers.
-
messageIdinteger path WymaganeId e-maila z listy skrzynki.
- 404Nie Twój numer albo nie ma jeszcze adresu.
- 404
private_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"
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77/body", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77/body",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77/body');
$result = $response->json();
{
"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 }
]
}
}
/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-
idinteger path WymaganeId numeru z GET /numbers.
-
messageIdinteger path WymaganeId e-maila z listy skrzynki.
-
indexinteger path Wymaganeattachments[].index z „Odczytaj e-mail”.
- 404Nie Twój numer albo nie ma jeszcze adresu.
- 404
private_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
import { writeFile } from "node:fs/promises";
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77/attachments/0", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
},
});
await writeFile("receipt.pdf", Buffer.from(await response.arrayBuffer()));
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77/attachments/0",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
},
timeout=30,
)
with open("receipt.pdf", "wb") as file:
file.write(response.content)
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->sink(storage_path('receipt.pdf'))
->get('https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77/attachments/0');
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename=receipt.pdf
<binary file>
/v1/numbers/{id}/private-email/inbox/{messageId}
Usuń e-mail
Usuwa e-mail i jego załączniki.
Parametry-
idinteger path WymaganeId numeru z GET /numbers.
-
messageIdinteger path WymaganeId e-maila z listy skrzynki.
- 404Nie Twój numer albo nie ma jeszcze adresu.
- 404
private_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"
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77", {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.delete(
"https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->delete('https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77');
$result = $response->json();
{
"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.
Endpointhttps://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ędzie | Co robi | Wymaga „Zezwól na zakupy” |
|---|---|---|
get-balance | Pobierz saldo portfela i walutę rozliczeń uwierzytelnionego konta. | Nie |
get-pricing | Zwróć aktywny cennik dla wszystkich krajów lub jednego kodu kraju ISO. | Nie |
get-inventory | Sprawdź bieżącą dostępność numerów dla kraju, okresu i opcjonalnie typu numeru. | Nie |
purchase-number | Kup jeden prywatny numer dla uwierzytelnionego konta ze środków w portfelu. | Tak |
list-active-numbers | Zwróć numery należące do uwierzytelnionego konta, opcjonalnie filtrowane według statusu. | Nie |
check-sms | Pobierz wiadomości SMS dla ID kupionego numeru należącego do uwierzytelnionego konta. | Nie |
renew-number | Odnów kupiony numer po ID, opcjonalnie wybierając pakiet okresu. | Tak |
cancel-number | Anuluj 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.
- Kliknij Dodaj do Claude. Claude otworzy się z już uzupełnioną nazwą Temp Number i jej URL. Kliknij Add.
- Kliknij Connect, zaloguj się do Temp Number, wybierz, czy Claude może dokonywać zakupów, i kliknij Zezwól.
- W dowolnym czacie otwórz menu + → Connectors i włącz Temp Number. Spróbuj: „Ile kosztuje numer z USA na miesiąc?”
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>.
ChatGPT
Wymaga ChatGPT Business, Enterprise lub Edu w wersji webowej. W planie Business dodaje go administrator lub właściciel.
- Skopiuj poniższy URL serwera, a następnie kliknij Otwórz ChatGPT, aby przejść na stronę Plugins. ChatGPT nie ma linku, który uzupełni to za Ciebie.
- Kliknij + → Add custom MCP server. Nazwij go Temp Number i wklej URL w polu Connection.
- Ustaw uwierzytelnianie na OAuth, zaakceptuj ostrzeżenie o ryzyku i kliknij Create as a plugin.
- Gdy ChatGPT poprosi, zaloguj się do Temp Number, wybierz, czy ChatGPT może dokonywać zakupów, i kliknij Zezwól.
- W nowym czacie wpisz @ i wybierz Temp Number. Spróbuj: „Ile kosztuje numer z USA na miesiąc?”
https://mcp.temp-number.com/mcp
Claude Code
Dodaj serwer raz, a potem zaloguj się z poziomu Claude Code.
claude mcp add --transport http temp-number https://mcp.temp-number.com/mcp
- Uruchom Claude Code i wpisz
/mcp. - Wybierz temp-number → Authenticate. Otworzy się przeglądarka: zaloguj się i kliknij Zezwól.
Użycie klucza MCP (CI / bez interfejsu)
export TEMPNUMBER_MCP_KEY=your-mcp-key
claude mcp add --transport http temp-number \
https://mcp.temp-number.com/mcp \
--header "Authorization: Bearer $TEMPNUMBER_MCP_KEY"
Codex CLI
Dodaj serwer, a potem się zaloguj. Codex zapamięta sesję za Ciebie.
codex mcp add temp-number --url https://mcp.temp-number.com/mcp
codex mcp login temp-number
Użycie klucza MCP (CI / bez interfejsu)
W pliku ~/.codex/config.toml. Klucz jest odczytywany ze zmiennych środowiskowych, więc plik można bezpiecznie udostępniać.
[mcp_servers.temp-number]
url = "https://mcp.temp-number.com/mcp"
bearer_token_env_var = "TEMPNUMBER_MCP_KEY"
Cursor
Jedno kliknięcie, potem logowanie, gdy Cursor o to poprosi.
Albo dodaj go do .cursor/mcp.json (lub ~/.cursor/mcp.json). Cursor pokaże wtedy Needs login obok serwera: kliknij, zaloguj się i kliknij Zezwól.
{
"mcpServers": {
"temp-number": {
"url": "https://mcp.temp-number.com/mcp"
}
}
}
Użycie klucza MCP
{
"mcpServers": {
"temp-number": {
"url": "https://mcp.temp-number.com/mcp",
"headers": {
"Authorization": "Bearer ${env:TEMPNUMBER_MCP_KEY}"
}
}
}
}
VS Code (GitHub Copilot)
Jedno kliknięcie, potem logowanie przy pierwszym użyciu narzędzia.
Albo dodaj go do .vscode/mcp.json – uwaga: klucz to servers, a nie mcpServers.
{
"servers": {
"temp-number": {
"type": "http",
"url": "https://mcp.temp-number.com/mcp"
}
}
}
Użycie klucza MCP
VS Code poprosi o klucz raz i przechowa go w swoim bezpiecznym magazynie sekretów.
{
"servers": {
"temp-number": {
"type": "http",
"url": "https://mcp.temp-number.com/mcp",
"headers": {
"Authorization": "Bearer ${input:tempnumber-mcp-key}"
}
}
},
"inputs": [
{
"type": "promptString",
"id": "tempnumber-mcp-key",
"description": "Temp Number MCP key",
"password": true
}
]
}
Dowolna inna aplikacja MCP
Windsurf, Zed, LibreChat, Twój własny agent…
- Dodaj endpoint MCP jako zdalny serwer (streamable HTTP). Aplikacje obsługujące logowanie same znajdą go pod
https://mcp.temp-number.com/.well-known/oauth-protected-resourcei otworzą ekran zgody Temp Number. - Aplikacje bez obsługi logowania mogą wysyłać klucz MCP jako
Authorization: Bearer <key>.
https://mcp.temp-number.com/mcp
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ń.
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ę.