API Temp Number - Numeri di telefono, SMS e OTP
Attiva numeri di telefono virtuali, ricevi SMS in tempo reale e automatizza la verifica OTP - da un'API REST pulita o direttamente dal tuo assistente IA.
https://api.temp-number.com/v1
Home / Sviluppatori
Introduzione
L'API di Temp Number è organizzata attorno a risorse prevedibili, usa i verbi HTTP standard e restituisce JSON per ogni risposta. Una chiave dà accesso in lettura e scrittura solo al tuo account - non esiste accesso tra account diversi.
Guida rapida
Da zero a un codice di verifica. Scegli il tuo linguaggio una volta - tutti gli esempi della pagina lo seguiranno.
-
Crea una chiave API
In Dashboard → Accesso API, crea una chiave. Viene mostrata una sola volta: salvala nella variabile d'ambiente
TEMP_NUMBER_API_KEY. -
Controlla il tuo saldo
Ogni chiamata invia la tua chiave nell'header Authorization. Inizia con qualcosa di innocuo: il saldo del tuo wallet.
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(); -
Scegli un paese e verifica la disponibilità
GET /pricing elenca tutti i paesi con il prezzo esatto per ogni durata. Poi verifica la disponibilità per quello che ti interessa.
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(); -
Acquista un numero
Invia una nuova Idempotency-Key con ogni acquisto. Se la rete cade, riprova con la stessa chiave: non ti verrà mai addebitato due volte. Conserva data.id dalla risposta.
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(); -
Leggi gli SMS
Interroga il numero ogni pochi secondi finché arriva il messaggio. Ricevi il testo grezzo; estrai il codice dal tuo lato.
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(); -
Nessun SMS? Annulla e ottieni un rimborso
Tra 15 e 120 minuti dopo l'acquisto, un numero che non ha ricevuto SMS può essere annullato con rimborso completo sul tuo wallet.
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();
Autenticazione
Invia la tua chiave API nell'header standard Authorization in ogni richiesta:
Authorization: Bearer YOUR_API_KEY
- Crea le chiavi in Accesso API. Una chiave viene mostrata per intero una sola volta, al momento della creazione.
- Usa una chiave per ogni integrazione, così puoi revocarne una senza bloccare le altre. Se cambi la password, tutte le chiavi vengono revocate.
- Una chiave mancante, non valida o revocata restituisce
401. Un account che non ha verificato l'email, o che è sospeso, restituisce403concodeemail_unverifiedoaccount_suspended. - Le chiavi REST funzionano solo su
/v1. Il server MCP usa un proprio accesso o chiavi MCP - vedi Server MCP.
URL di base e versioni
Tutti gli endpoint si trovano sotto il prefisso permanente /v1:
https://api.temp-number.com/v1
Le modifiche additive - nuovi campi, endpoint o parametri opzionali - vengono rilasciate senza cambio di versione, quindi ignora i campi che non conosci. Una modifica incompatibile verrebbe rilasciata sotto /v2; la tua integrazione non viene mai spostata senza avviso. Il contratto leggibile dalle macchine è la specifica OpenAPI.
Richieste e risposte
- Invia corpi JSON con
Content-Type: application/jsoneAccept: application/jsonin ogni richiesta. - Successo:
{ "success": true, "data": …, "meta": {…} }.metacontiene conteggi, paginazione e riepiloghi degli importi. - Errori:
{ "success": false, "message": "…", "code": "…" }. Gestisci i casi in base acode; il messaggio è per le persone. Vedi Errori. - Gli orari sono in formato ISO 8601. Gli importi sono in USD con due decimali: sempre il prezzo che paghi.
- Alcuni oggetti mantengono ancora nomi di campo precedenti per le integrazioni esistenti (contrassegnati come deprecati nel riferimento). Il nuovo codice dovrebbe ignorarli.
Errori
Gli errori usano i codici di stato HTTP standard. Gli errori di business includono un code stabile e leggibile dalle macchine; alcuni includono details con ulteriore contesto.
{
"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."]
}
}
| Stato | code | Significato | Cosa fare |
|---|---|---|---|
| 400 | - | L'header Idempotency-Key è mancante o non valido in acquisto, rinnovo o annullamento. Corpo: {"error": "Missing Idempotency-Key header."} | Invia un UUID in Idempotency-Key. |
| 401 | - | Token bearer assente o non valido, oppure chiave revocata. | Controlla l'header Authorization; crea una nuova chiave se è stata revocata. |
| 403 | email_unverified |
L'account non ha ancora verificato il proprio indirizzo email. | Verifica l'email sul sito, poi riprova. |
| 403 | account_suspended |
L'account è sospeso. | Contatta l'assistenza. |
| 403 | kyc_required |
L'account deve verificare la propria identità prima di acquistare nuovi numeri. Nessun addebito; i rinnovi funzionano ancora. | Completa la verifica dell'identità nelle impostazioni dell'account, poi riprova. |
| 403 | - | La chiave non ha accesso all'API (ad esempio una chiave MCP), oppure GET /receive-sms è stato richiesto per un numero di un altro account. | Usa una chiave REST API; interroga solo i tuoi numeri. |
| 404 | - | Il numero, il messaggio o il paese non è nel tuo account o non è in vendita al momento. Anche gli id di altri account rispondono 404. | Rielenca con GET /numbers o GET /pricing. |
| 404 | private_email_closed |
La casella privata è chiusa perché il suo numero è stato annullato o rimborsato. | Nulla da ritentare. |
| 409 | - | La Idempotency-Key è già stata usata con un corpo diverso, oppure la prima richiesta con essa è ancora in corso. | Usa una nuova chiave per una nuova richiesta; per quella in corso, attendi e riprova. |
| 422 | insufficient_funds |
Il saldo del wallet non copre il prezzo. | Ricarica il wallet e riprova. |
| 422 | out_of_stock |
Il mercato si è esaurito tra la verifica del prezzo e l'acquisto. | Ricontrolla GET /inventory e scegli un'altra durata o un altro tipo. |
| 422 | invalid_duration |
La durata non è venduta per quel paese e quel tipo di numero. | Richiama di nuovo GET /pricing/{countryCode}. |
| 422 | - | Convalida non riuscita (un oggetto `errors` indica ogni campo) oppure una regola ha rifiutato l'azione, ad esempio un annullamento fuori dal periodo di rimborso. | Leggi `message`; correggi la richiesta invece di ritentarla. |
| 429 | - | Limite di frequenza raggiunto. | Attendi quanto indicato dall'header Retry-After, poi riprova con backoff. |
| 503 | purchases_paused |
I nuovi acquisti sono sospesi su tutta la piattaforma. Nessun addebito; rinnovi e annullamenti funzionano ancora. | Riprova dopo Retry-After (60 s). |
| 5xx | - | Qualcosa non ha funzionato da parte nostra. | Riprova con la STESSA Idempotency-Key: non ti verrà mai addebitato due volte. |
Limiti di frequenza
I limiti si applicano per chiave, e le chiamate che movimentano denaro hanno in più un limite più stretto per account:
| Si applica a | Limite | Conteggiato |
|---|---|---|
| Tutti gli endpoint | 60 / minuto | per chiave API |
| Acquista, rinnova, annulla | 10 / minuto | per account, in aggiunta ai limiti sopra |
| GET /receive-sms | 60 / minuto | per chiave API |
| GET /receive-sms | 30 / minuto | per chiave API e numero di telefono |
| GET /receive-sms | 30 / minuto | per indirizzo IP |
Oltre un limite ricevi 429 con un header Retry-After (in secondi). Attendi almeno quel tempo, poi riprova con backoff e jitter. Le risposte includono anche X-RateLimit-Limit e X-RateLimit-Remaining.
Idempotenza
POST /numbers/buy, /renew e /cancel richiedono un header Idempotency-Key: un UUID che crei per ogni nuova azione. Se la connessione cade, invia la stessa richiesta con la stessa chiave - riceverai la risposta originale (contrassegnata con X-Idempotency-Replayed: true) e non ti verrà mai addebitato due volte.
- Chiave mancante:
400. Le chiavi possono contenere fino a 128 caratteri tra lettere, cifre e- _ . : - Stessa chiave con un corpo diverso:
409. Stessa chiave mentre la prima richiesta è ancora in corso:409- attendi un momento e riprova. - Le chiavi vengono memorizzate per account ed endpoint. Non riutilizzarne mai una per un acquisto diverso.
Paginazione
GET /receive-sms usa la paginazione a cursore, dal più recente. Leggi meta.hasMore; finché è true, rimanda meta.nextCursor come cursor con lo stesso phoneNumber. I cursori sono opachi - non costruirli né modificarli.
GET https://api.temp-number.com/v1/receive-sms?phoneNumber=%2B14035551234&limit=50&cursor=eyJkYXRlIjoiMjAyNi0wNS0xMyJ9
Gli elenchi piccoli per natura (/numbers, /pricing) restituiscono tutto in un'unica risposta; la posta privata usa page e per_page.
Uso consentito
L'API è pensata per gli sviluppatori: flussi di verifica e OTP, onboarding automatizzato, QA e test di sistema, e qualsiasi prodotto che richieda SMS in arrivo o numeri di telefono su larga scala.
- Usalo solo per verifiche legittime, sviluppo e test.
- Niente truffe, spam, frodi o inganni. Se i numeri vengono usati per truffe o altre attività abusive, l'account viene bannato immediatamente e senza preavviso, i numeri associati vengono annullati e non è dovuto alcun rimborso.
- Non adatto ad account regolamentati o legati all'identità. I nostri numeri temporanei condivisi non supportano la verifica via SMS per banche, pagamenti, criptovalute, servizi pubblici o altri servizi che verificano la tua identità legale (KYC/AML) - per questi usa il tuo numero di cellulare personale.
Riferimento API
Ogni endpoint /v1 attivo. Le richieste sono a destra nel tuo linguaggio; le risposte hanno la struttura reale.
Account
Leggi il saldo del tuo wallet e la valuta di regolamento.
/v1/account
Ottieni il saldo dell'account
Restituisce il saldo disponibile del wallet e la sua valuta. Controllalo prima di un acquisto, così puoi fermarti subito con un chiaro messaggio di "ricarica".
Campi della risposta-
balancenumberSaldo disponibile del wallet.
-
currencystringValuta di regolamento, USD.
- 401Chiave mancante o non valida.
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"
}
Prezzi e disponibilità
Consulta i mercati attivi, il prezzo esatto che paghi per ogni durata e la disponibilità in tempo reale.
L'oggetto prezzo per paese
Un paese e tutti i pacchetti che puoi acquistare lì. price è l'importo finale addebitato sul tuo wallet; il costo a monte non viene mai mostrato.
Campi-
country_codestringCodice ISO 3166-1 alpha-2, ad es. US.
-
country_namestringNome visualizzato.
-
packages[].number_typeenumvoip o non_voip.
-
packages[].durationenumLa chiave da inviare per acquistare: halfDay, oneDay, oneWeek, oneMonth, threeMonths, sixMonths o oneYear. Ogni paese offre il proprio insieme.
-
packages[].duration_labelstringEtichetta leggibile, ad es. "1 Month".
-
packages[].pricenumberPrezzo finale in USD.
-
packages[].original_pricenumber | nullIl prezzo prima dello sconto, se applicato.
-
packages[].updated_atnullRiservato.
{
"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
Elenca i prezzi per tutti i paesi
Il catalogo completo in tempo reale: un elenco di oggetti prezzo per paese. Il campo price è la tariffa finale per l'utente in USD, esattamente quanto viene addebitato sul tuo wallet.
RestituisceUn elenco di oggetti prezzo per paese in data, con meta.count.
Errori- 401Chiave mancante o non valida.
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}
Ottieni i prezzi per un paese
Prezzi in tempo reale per un singolo paese. Un 404 significa che al momento il paese non ha una route attiva: consideralo un "esaurito" temporaneo, non un "mai venduto".
Parametri-
countryCodestring path ObbligatorioCodice paese ISO 3166-1 alpha-2, ad es. US, GB, CA.
Un oggetto prezzo per paese in data.
Errori- 404Al momento nessuna route attiva per quel paese.
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
Verifica disponibilità
Disponibilità in tempo reale per un paese e una durata, così puoi disattivare un pulsante Acquista prima che qualcuno lo clicchi. Ometti number_type per ottenere tutti i tipi affiancati in types[]. Un risultato verde è un buon segnale, ma la verifica finale è l'acquisto stesso.
Parametri-
country_codestring query ObbligatorioCodice paese ISO 3166-1 alpha-2.
-
durationenum query FacoltativoUna chiave di durata da GET /pricing/{countryCode}. Omettila per usare quella predefinita della route.
Uno trahalfDayoneDayoneWeekoneMonththreeMonthssixMonthsoneYear -
number_typeenum query FacoltativoLimita la verifica a un tipo. Omettilo per vedere tutti i tipi.
Uno travoipnon_voip
-
stockinteger | nullNumeri disponibili (sommati su types[] quando number_type è omesso).
-
availablebooleanTrue quando è possibile acquistare almeno un numero.
-
statusstringEtichetta leggibile: In Stock, Out of Stock, Coming Soon…
-
types[]arraySolo quando number_type è omesso: number_type, stock, available, status per ogni tipo venduto dal mercato.
- 422Nulla in vendita per quella selezione; details contiene i campi di disponibilità.
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" }
]
}
}
Numeri
Elenca, acquista, rinnova e annulla i tuoi numeri privati. Le chiamate che muovono denaro sono idempotenti e sicure in caso di ripetizione.
L'oggetto numero
Un numero del tuo account. Acquisto, rinnovo e annullamento restituiscono anche un riepilogo economico in meta: charged (o refunded), currency e wallet_balance_after.
Campi-
idintegerUsalo nelle chiamate /numbers/{id}/…. I webhook lo inviano come number.rentalId.
-
phone_numberstringE.164, ad es. +14035551234.
-
country_codestring | nullISO 3166-1 alpha-2.
-
country_namestringNome visualizzato.
-
number_typeenumvoip o non_voip.
-
statusenumactive, expired, cancelled o refunded.
-
purchase_datestringISO 8601, UTC.
-
expire_datestringISO 8601, UTC. Dopo questa data il numero smette di ricevere SMS e non può essere rinnovato.
Alias deprecati ancora inviati per le integrazioni meno recenti: country, provider, purchased_at ed expires_at (millisecondi epoch). Non basarti su di essi.
{
"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
Elenca i tuoi numeri
Tutti i numeri del tuo account, dai più recenti. Usa status=expiring_soon (numeri attivi a meno di 10 giorni dalla scadenza) per gestire i promemoria di rinnovo.
Parametri-
statusenum query FacoltativoFiltro per stato del ciclo di vita. Predefinito all.
Uno traallactiveexpiring_soonexpiredcancelled
Un elenco di oggetti numero in data; meta.count e meta.status.
Errori- 401Chiave mancante o non valida.
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
Idempotency-Key obbligatoria Acquista un numero
Assegna un nuovo numero privato e addebita il tuo wallet in un unico passaggio atomico. Se l'evasione non riesce dopo l'addebito, l'addebito viene stornato: non paghi mai senza ricevere nulla. La risposta mostra l'importo addebitato e il saldo successivo.
Parametri-
country_codestring body ObbligatorioUn paese restituito da GET /pricing.
-
durationenum body ObbligatorioUna chiave di durata dai packages[] di quel paese: ogni paese offre il proprio insieme.
Uno trahalfDayoneDayoneWeekoneMonththreeMonthssixMonthsoneYear -
number_typeenum body FacoltativoOmettilo per usare il valore predefinito della route.
Uno travoipnon_voip -
Idempotency-Keystring header ObbligatorioUn UUID, nuovo per ogni acquisto, riutilizzato nei tentativi successivi.
Il nuovo oggetto numero in data; meta.charged, meta.currency, meta.wallet_balance_after.
Errori- 422
insufficient_fundsIl saldo del wallet non copre il prezzo. - 422
out_of_stockEsaurito dopo la tua verifica di disponibilità. - 422
invalid_durationDurata non venduta per questo paese/tipo. - 403
kyc_requiredPrima è necessaria la verifica dell'identità. Nessun addebito. - 503
purchases_pausedAcquisti sospesi su tutta la piattaforma. 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
Idempotency-Key obbligatoria Rinnova un numero
Prolunga un numero con il pacchetto scelto. Il nuovo periodo si aggiunge alla scadenza attuale, quindi rinnovare in anticipo non fa perdere nulla. Il prezzo è la tariffa attuale del sito, calcolata da noi. I numeri scaduti non possono essere rinnovati: acquistane uno nuovo.
Parametri-
idinteger path ObbligatorioId del numero da GET /numbers.
-
packageenum body FacoltativoDurata del rinnovo. Predefinito oneMonth. (duration è accettato come alias legacy.)
Uno traoneMonththreeMonthssixMonthsoneYear -
Idempotency-Keystring header ObbligatorioUn UUID, nuovo per ogni rinnovo, riutilizzato nei tentativi successivi.
L'oggetto numero aggiornato in data; meta.charged, meta.currency, meta.wallet_balance_after.
Errori- 404Non è un numero del tuo account.
- 422
insufficient_fundsIl saldo del wallet non copre il rinnovo. - 422Scaduto, annullato o non rinnovabile.
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
Idempotency-Key obbligatoria Annulla un numero per ottenere un rimborso
Rilascia un numero e rimborsa l'intero prezzo sul tuo wallet. Consentito solo tra 15 e 120 minuti dopo l'acquisto, mentre il numero è attivo e prima che abbia ricevuto SMS. Al di fuori di queste regole la chiamata viene rifiutata con 422 e non cambia nulla; se è troppo presto, details.seconds_until_open indica quanto attendere.
Parametri-
idinteger path ObbligatorioId del numero da GET /numbers.
-
Idempotency-Keystring header ObbligatorioUn UUID, riutilizzato nei tentativi successivi.
L'oggetto numero (status cancelled) in data; meta.refunded, meta.currency, meta.wallet_balance_after.
Errori- 404Non è un numero del tuo account.
- 422Troppo presto (meno di 15 min), troppo tardi (oltre 120 min), SMS già ricevuti oppure non attivo.
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
Leggi gli SMS ricevuti dai tuoi numeri. Ricevi il testo grezzo; l'estrazione del codice spetta a te.
L'oggetto messaggio SMS
Un SMS ricevuto, come restituito da GET /numbers/{id}/sms. (GET /receive-sms usa una variante camelCase, mostrata in quell'endpoint.)
Campi-
idintegerId del messaggio.
-
fromstringMittente: un numero di telefono o un nome come WhatsApp.
-
bodystringIl testo completo del messaggio.
-
received_atstringISO 8601, UTC.
Alias deprecati ancora inviati: sender (= from) e message (= body).
{
"id": 9912,
"from": "+18005550199",
"body": "Your code is 432901",
"received_at": "2026-05-13T17:43:14Z"
}
/v1/numbers/{id}/sms
Ottieni un numero e i suoi SMS
Un numero insieme a tutti gli SMS che ha ricevuto, dai più recenti. Ideale per una vista di "dettaglio del numero" e per interrogare un singolo numero mentre aspetti un codice. Gli id che non sono tuoi rispondono 404.
Parametri-
idinteger path ObbligatorioId del numero da GET /numbers.
data.number (un oggetto numero) e data.messages (oggetti messaggio SMS); meta.count.
Errori- 404Non è un numero del tuo account.
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
Ricevi SMS per numero di telefono
SMS paginati con cursore per un numero di tua proprietà, indicato tramite numero di telefono anziché id. Ideale per caselle con molti messaggi. Un numero che non è tuo risponde 403.
Parametri-
phoneNumberstring query ObbligatorioE.164 o solo cifre, ad es. +14035551234. Codifica il + nell'URL.
-
limitinteger query FacoltativoDimensione pagina 1-100. Predefinito 50.
-
cursorstring query Facoltativometa.nextCursor della pagina precedente.
-
data.messages[].idintegerId del messaggio.
-
data.messages[].fromstringMittente.
-
data.messages[].tostringIl tuo numero.
-
data.messages[].messagestringIl testo completo.
-
data.messages[].receivedAtstringISO 8601.
-
meta.hasMore / nextCursorboolean / string | nullPassa nextCursor come cursor per la pagina successiva.
- 403Il numero non è nel tuo account.
- 422phoneNumber mancante o non valido.
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"
}
}
Email privata
Una casella [email protected] gratuita e di sola ricezione per ogni numero privato. Un indirizzo per numero.
L'oggetto email privata
La casella collegata a un numero.
Campi-
addressstring | nullL'indirizzo, oppure null prima dell'attivazione.
-
statusenumactive o none.
-
unread_countintegerEmail non lette.
-
created_atstring | nullQuando l'indirizzo è stato attivato.
-
eligiblebooleanTrue quando il numero può attivare subito un indirizzo.
-
linked_numberstringIl numero di telefono a cui appartiene.
-
domainstringprivnum.com
-
suggestionsstring[]Suggerimenti di nomi finché il numero è idoneo.
{
"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
Ottieni l'email privata
L'indirizzo di un numero oppure, prima dell'attivazione, se può averne uno e alcuni suggerimenti di nomi.
Parametri-
idinteger path ObbligatorioId del numero da GET /numbers.
Un oggetto email privata in data.
Errori- 404Non è un numero del tuo account.
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
Verifica un nome
Verifica in tempo reale che un nome sia valido e libero prima di attivarlo.
Parametri-
idinteger path ObbligatorioId del numero da GET /numbers.
-
local_partstring query ObbligatorioLa parte prima di @: 3-64 lettere, numeri, punti, trattini o trattini bassi.
-
availablebooleanTrue quando puoi attivarlo.
-
reasonenum | nulltoo_short, too_long, invalid, reserved o taken.
- 404Non è un numero del tuo account.
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
Attiva un indirizzo
Assegna un indirizzo a un numero attivo. Gratuito, uno per numero, e un indirizzo attivato non viene mai assegnato a nessun altro.
Parametri-
idinteger path ObbligatorioId del numero da GET /numbers.
-
local_partstring body ObbligatorioIl nome che hai verificato.
L'oggetto email privata in data.
Errori- 404Non è un tuo numero, oppure non ha ancora un indirizzo.
- 422Nome già in uso o non valido (details.reason), il numero ha già un indirizzo oppure non è attivo.
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
Elenca le email
Riepiloghi delle email, dalle più recenti, con paginazione a pagine e il numero di non lette al livello principale.
Parametri-
idinteger path ObbligatorioId del numero da GET /numbers.
-
pageinteger query FacoltativoNumero di pagina. Predefinito 1.
-
per_pageinteger query Facoltativo1-100. Predefinito 25.
-
data[]arrayid, from_email, from_name, subject, preview, attachment_count, is_read, received_at.
-
metaobjectcurrent_page, per_page, total, last_page.
-
unread_countintegerAl livello principale, accanto a data.
- 404Non è un tuo numero, oppure non ha ancora un indirizzo.
- 404
private_email_closedIl numero è stato annullato o rimborsato.
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
Leggi un'email
L'email completa (HTML e testo) con l'elenco degli allegati. Leggerla la segna come letta.
Parametri-
idinteger path ObbligatorioId del numero da GET /numbers.
-
messageIdinteger path ObbligatorioId dell'email dall'elenco della casella.
- 404Non è un tuo numero, oppure non ha ancora un indirizzo.
- 404
private_email_closedIl numero è stato annullato o rimborsato.
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}
Scarica un allegato
Il file originale, con il proprio Content-Type e nome file. index proviene da attachments[] dell'email.
Parametri-
idinteger path ObbligatorioId del numero da GET /numbers.
-
messageIdinteger path ObbligatorioId dell'email dall'elenco della casella.
-
indexinteger path Obbligatorioattachments[].index da Leggi un'email.
- 404Non è un tuo numero, oppure non ha ancora un indirizzo.
- 404
private_email_closedIl numero è stato annullato o rimborsato. - 404Nessun allegato a quell'indice.
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}
Elimina un'email
Elimina l'email e i suoi allegati.
Parametri-
idinteger path ObbligatorioId del numero da GET /numbers.
-
messageIdinteger path ObbligatorioId dell'email dall'elenco della casella.
- 404Non è un tuo numero, oppure non ha ancora un indirizzo.
- 404
private_email_closedIl numero è stato annullato o rimborsato.
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 e MCP
Lascia che un assistente AI usi direttamente il tuo account, oppure fornisci a un agente di programmazione tutto ciò che serve per sviluppare con l'API.
Server MCP
Oltre all'API REST offriamo un server Model Context Protocol. Collegalo a Claude, ChatGPT o al tuo editor e l'assistente potrà controllare prezzi e disponibilità, acquistare un numero e leggerne gli SMS come strumenti nativi, senza scrivere codice. Non conosci MCP? Inizia dalla panoramica del server MCP.
Endpointhttps://mcp.temp-number.com/mcp
Come funziona l'accesso
- Aggiungi l'URL alla tua app AI. Ti porterà su Temp Number per accedere con il tuo account (OAuth 2.1 con PKCE): nessuna chiave da copiare.
- Nella schermata di consenso scegli cosa può fare l'assistente. La lettura di saldo, prezzi, dei tuoi numeri e dei loro SMS è sempre inclusa. Consenti acquisti (acquistare, rinnovare e annullare con il tuo wallet) resta disattivato finché non lo selezioni.
- Ogni connessione è elencata in Dashboard → Server MCP → App collegate, dove puoi scollegarla in qualsiasi momento.
- Preferisci una chiave (CI, script, agenti headless)? Crea una chiave MCP nella stessa pagina e inviala come
Authorization: Bearer <key>. Le chiavi MCP e le chiavi API REST non sono intercambiabili.
Strumenti
| Strumento | Cosa fa | Richiede "Consenti acquisti" |
|---|---|---|
get-balance | Recupera il saldo del portafoglio e la valuta di fatturazione dell'account autenticato. | No |
get-pricing | Restituisce il listino prezzi attivo per tutti i paesi o per un singolo codice paese ISO. | No |
get-inventory | Controlla la disponibilità dell'inventario in tempo reale per un paese, una durata e un tipo di numero facoltativo. | No |
purchase-number | Acquista un numero privato per l'account autenticato usando i fondi del portafoglio. | Sì |
list-active-numbers | Restituisce i numeri dell'account autenticato, con filtro facoltativo per stato. | No |
check-sms | Recupera i messaggi SMS di un numero acquistato, tramite ID, di proprietà dell'account autenticato. | No |
renew-number | Rinnova un numero acquistato tramite ID, con un pacchetto di durata facoltativo. | Sì |
cancel-number | Annulla un numero acquistato tramite ID e restituisce al portafoglio l'eventuale rimborso spettante. | Sì |
Collega il tuo strumento AI
Scegli la tua app. La maggior parte si collega con un clic: accedi a Temp Number, selezioni cosa può fare l'assistente e fai clic su Consenti.
Claude - claude.ai, desktop e mobile
Niente da installare. Funziona nel browser, nell'app desktop e su mobile.
- Fai clic su Aggiungi a Claude. Claude si apre con Temp Number e il suo URL già compilati. Fai clic su Aggiungi.
- Fai clic su Connetti, accedi a Temp Number, scegli se Claude può effettuare acquisti e fai clic su Consenti.
- In qualsiasi chat, apri il menu + → Connettori e attiva Temp Number. Prova: "Quanto costa un numero USA per un mese?"
Nessun pulsante? In Claude vai su Personalizza → Connettori → Aggiungi connettore personalizzato e incolla l'endpoint MCP. Le organizzazioni con l'opzione di intestazione della richiesta di Claude possono inviare una chiave MCP come Authorization: Bearer <key> invece di accedere.
ChatGPT
Richiede ChatGPT Business, Enterprise o Edu sul web. Con Business lo aggiunge un amministratore o il proprietario.
- Copia l'URL del server qui sotto, poi fai clic su Apri ChatGPT per andare alla pagina Plugin. ChatGPT non ha un link che compili questi dati per te.
- Fai clic su + → Add custom MCP server. Chiamalo Temp Number e incolla l'URL in Connection.
- Imposta l'autenticazione su OAuth, accetta l'avviso di rischio e fai clic su Create as a plugin.
- Quando ChatGPT lo chiede, accedi a Temp Number, scegli se ChatGPT può effettuare acquisti e fai clic su Consenti.
- In una nuova chat, digita @ e scegli Temp Number. Prova: "Quanto costa un numero USA per un mese?"
https://mcp.temp-number.com/mcp
Claude Code
Aggiungi il server una volta, poi accedi direttamente da Claude Code.
claude mcp add --transport http temp-number https://mcp.temp-number.com/mcp
- Avvia Claude Code e digita
/mcp. - Scegli temp-number → Authenticate. Si apre il browser: accedi e fai clic su Consenti.
Usare invece una chiave MCP (CI / headless)
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
Aggiungi il server, poi accedi. Codex salva la sessione per te.
codex mcp add temp-number --url https://mcp.temp-number.com/mcp
codex mcp login temp-number
Usare invece una chiave MCP (CI / headless)
In ~/.codex/config.toml. La chiave viene letta dall'ambiente, quindi il file si può condividere in sicurezza.
[mcp_servers.temp-number]
url = "https://mcp.temp-number.com/mcp"
bearer_token_env_var = "TEMPNUMBER_MCP_KEY"
Cursor
Un clic, poi accedi quando Cursor lo chiede.
Oppure aggiungilo a .cursor/mcp.json (o ~/.cursor/mcp.json). Cursor mostrerà Needs login accanto al server: fai clic, accedi e fai clic su Consenti.
{
"mcpServers": {
"temp-number": {
"url": "https://mcp.temp-number.com/mcp"
}
}
}
Usare invece una chiave MCP
{
"mcpServers": {
"temp-number": {
"url": "https://mcp.temp-number.com/mcp",
"headers": {
"Authorization": "Bearer ${env:TEMPNUMBER_MCP_KEY}"
}
}
}
}
VS Code (GitHub Copilot)
Un clic, poi accedi la prima volta che viene eseguito uno strumento.
Oppure aggiungilo a .vscode/mcp.json: nota che la chiave è servers, non mcpServers.
{
"servers": {
"temp-number": {
"type": "http",
"url": "https://mcp.temp-number.com/mcp"
}
}
}
Usare invece una chiave MCP
VS Code chiede la chiave una sola volta e la conserva nel suo archivio segreto.
{
"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
}
]
}
Qualsiasi altra app MCP
Windsurf, Zed, LibreChat, il tuo agente…
- Aggiungi l'endpoint MCP come server remoto (HTTP streamable). Le app che supportano l'accesso lo trovano da sole su
https://mcp.temp-number.com/.well-known/oauth-protected-resourcee aprono la schermata di consenso di Temp Number. - Le app che non supportano l'accesso possono inviare una chiave MCP come
Authorization: Bearer <key>.
https://mcp.temp-number.com/mcp
llms.txt e prompt per agenti
Sviluppi con un assistente di programmazione AI? Forniscigli il contesto qui sotto e potrà integrare l'API correttamente al primo colpo, autenticazione, idempotenza e limiti di frequenza inclusi.
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 è un riepilogo in testo semplice, sempre aggiornato, di tutti gli endpoint; la specifica OpenAPI è il contratto tipizzato. Entrambi si aggiornano insieme all'API.Risorse
Cosa è cambiato e dove trovare assistenza.
Changelog
Solo modifiche additive - nulla è stato rimosso da /v1.
-
NewMCP: accedi con il tuo account Temp Number
"Add to Claude" con un clic, oltre a ChatGPT, Claude Code, Codex, Cursor e VS Code senza copiare alcuna chiave. Nella schermata di consenso scegli se l'AI può spendere.
-
DocsUna nuova casa per la documentazione
Guida rapida, ricerca e ogni esempio in cURL, Node.js, Python e PHP. Errori, limiti di frequenza e rimborsi ora corrispondono esattamente all'API attiva.
-
Newllms.txt per l'intero sito
Una mappa del servizio in testo semplice per gli assistenti AI, con link al riferimento API pronto per gli agenti.
-
NewCollega il tuo strumento AI
Configurazione per Claude Code, Codex, Cursor e VS Code, con link di installazione con un clic per Cursor e VS Code.
-
NewSpecifica OpenAPI
La specifica leggibile dalle macchine è disponibile su https://api.temp-number.com/api.json.
-
ImprovedGli oggetti corrispondono al riferimento
Numeri e SMS usano date ISO 8601 e from/body. Gli errori includono un codice leggibile dalle macchine (out_of_stock, insufficient_funds, invalid_duration). /inventory riporta tutti i tipi di numero quando ometti number_type. I vecchi nomi dei campi funzionano ancora come alias deprecati.
-
NewEndpoint email privata
Attiva una casella [email protected] gratuita per un numero, leggi la posta e scarica gli allegati tramite l'API.
-
NewServer MCP
Gli agenti AI possono controllare i prezzi, acquistare numeri e leggere gli SMS come strumenti, usando una chiave MCP.
-
LaunchREST API pubblica v1
Account, prezzi, disponibilità, ciclo di vita dei numeri e SMS, con autenticazione tramite token Bearer.
Assistenza
Bloccato, o hai trovato in questa documentazione qualcosa che non corrisponde al comportamento dell'API? Contattaci - indica l'endpoint, l'ora della richiesta e il corpo della risposta (mai la tua chiave API).
Pronto a sviluppare?
Crea una chiave ed effettua la tua prima chiamata in meno di un minuto.