Piattaforma per sviluppatori

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.

REST · JSON MCP per agenti IA cURL · Node.js · Python · PHP
URL DI BASE 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.

ProtocolloHTTPS · JSON
AutenticazioneChiave Bearer
Versionev1 (stabile)
Endpoint17 attivi

Guida rapida

Da zero a un codice di verifica. Scegli il tuo linguaggio una volta - tutti gli esempi della pagina lo seguiranno.

  1. 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.

  2. 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"
  3. 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"
  4. 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"}'
  5. 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"
  6. 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)"

Autenticazione

Invia la tua chiave API nell'header standard Authorization in ogni richiesta:

http
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, restituisce 403 con code email_unverified o account_suspended.
  • Le chiavi REST funzionano solo su /v1. Il server MCP usa un proprio accesso o chiavi MCP - vedi Server MCP.
Tratta la tua chiave come una password. Conservala sul tuo server, mai in una pagina web o in un'app mobile. Ruotala subito se è mai stata registrata nei log, inclusa in un commit o condivisa.

URL di base e versioni

Tutti gli endpoint si trovano sotto il prefisso permanente /v1:

URL di base
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/json e Accept: application/json in ogni richiesta.
  • Successo: { "success": true, "data": …, "meta": {…} }. meta contiene conteggi, paginazione e riepiloghi degli importi.
  • Errori: { "success": false, "message": "…", "code": "…" }. Gestisci i casi in base a code; 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.
Le risposte non indicano mai un fornitore a monte né mostrano costi all'ingrosso. L'unico prezzo che vedi è quello addebitato al tuo portafoglio - puoi mostrarlo tranquillamente ai tuoi utenti.

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.

422 · errore di business
{
  "success": false,
  "message": "Insufficient wallet balance.",
  "code": "insufficient_funds"
}
422 · errore di validazione
{
  "message": "The country code field is required.",
  "errors": {
    "country_code": ["The country code field is required."]
  }
}
StatocodeSignificatoCosa 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 aLimiteConteggiato
Tutti gli endpoint60 / minutoper chiave API
Acquista, rinnova, annulla10 / minutoper account, in aggiunta ai limiti sopra
GET /receive-sms60 / minutoper chiave API
GET /receive-sms30 / minutoper chiave API e numero di telefono
GET /receive-sms30 / minutoper 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.

In attesa di un SMS? Interroga un numero al massimo ogni 5 secondi.

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.

pagina successiva
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.
Monitoriamo gli abusi. Le condizioni complete sono nei nostri Termini di servizio.

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.

GET /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
  • balancenumber

    Saldo disponibile del wallet.

  • currencystring

    Valuta di regolamento, USD.

Errori
  • 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"
Risposta
{
  "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_codestring

    Codice ISO 3166-1 alpha-2, ad es. US.

  • country_namestring

    Nome visualizzato.

  • packages[].number_typeenum

    voip o non_voip.

  • packages[].durationenum

    La chiave da inviare per acquistare: halfDay, oneDay, oneWeek, oneMonth, threeMonths, sixMonths o oneYear. Ogni paese offre il proprio insieme.

  • packages[].duration_labelstring

    Etichetta leggibile, ad es. "1 Month".

  • packages[].pricenumber

    Prezzo finale in USD.

  • packages[].original_pricenumber | null

    Il prezzo prima dello sconto, se applicato.

  • packages[].updated_atnull

    Riservato.

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

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.

Restituisce

Un 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"
Risposta
{
  "success": true,
  "data": [
    {
      "country_code": "US",
      "country_name": "United States",
      "packages": [
        {
          "number_type": "voip",
          "duration": "oneMonth",
          "duration_label": "1 Month",
          "price": 4.99,
          "original_price": 5.99,
          "updated_at": null
        },
        {
          "number_type": "voip",
          "duration": "threeMonths",
          "duration_label": "3 Months",
          "price": 12.99,
          "original_price": null,
          "updated_at": null
        }
      ]
    }
  ],
  "meta": { "count": 1 }
}
GET /v1/pricing/{countryCode}

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
  • countryCode string path Obbligatorio

    Codice paese ISO 3166-1 alpha-2, ad es. US, GB, CA.

Restituisce

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"
Risposta
{
  "success": true,
  "data": {
    "country_code": "GB",
    "country_name": "United Kingdom",
    "packages": [
      {
        "number_type": "voip",
        "duration": "oneMonth",
        "duration_label": "1 Month",
        "price": 5.49,
        "original_price": null,
        "updated_at": null
      }
    ]
  }
}
GET /v1/inventory

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_code string query Obbligatorio

    Codice paese ISO 3166-1 alpha-2.

  • duration enum query Facoltativo

    Una chiave di durata da GET /pricing/{countryCode}. Omettila per usare quella predefinita della route.

    Uno tra halfDayoneDayoneWeekoneMonththreeMonthssixMonthsoneYear
  • number_type enum query Facoltativo

    Limita la verifica a un tipo. Omettilo per vedere tutti i tipi.

    Uno tra voipnon_voip
Campi della risposta
  • stockinteger | null

    Numeri disponibili (sommati su types[] quando number_type è omesso).

  • availableboolean

    True quando è possibile acquistare almeno un numero.

  • statusstring

    Etichetta leggibile: In Stock, Out of Stock, Coming Soon…

  • types[]array

    Solo quando number_type è omesso: number_type, stock, available, status per ogni tipo venduto dal mercato.

Errori
  • 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"
Risposta
{
  "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
  • idinteger

    Usalo nelle chiamate /numbers/{id}/…. I webhook lo inviano come number.rentalId.

  • phone_numberstring

    E.164, ad es. +14035551234.

  • country_codestring | null

    ISO 3166-1 alpha-2.

  • country_namestring

    Nome visualizzato.

  • number_typeenum

    voip o non_voip.

  • statusenum

    active, expired, cancelled o refunded.

  • purchase_datestring

    ISO 8601, UTC.

  • expire_datestring

    ISO 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.

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

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
  • status enum query Facoltativo

    Filtro per stato del ciclo di vita. Predefinito all.

    Uno tra allactiveexpiring_soonexpiredcancelled
Restituisce

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"
Risposta
{
  "success": true,
  "data": [
    {
      "id": 1482,
      "phone_number": "+14035551234",
      "country_code": "US",
      "country_name": "United States",
      "number_type": "voip",
      "status": "active",
      "purchase_date": "2026-05-13T17:42:09Z",
      "expire_date": "2026-06-13T17:42:09Z"
    }
  ],
  "meta": { "count": 1, "status": "expiring_soon" }
}
POST /v1/numbers/buy 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_code string body Obbligatorio

    Un paese restituito da GET /pricing.

  • duration enum body Obbligatorio

    Una chiave di durata dai packages[] di quel paese: ogni paese offre il proprio insieme.

    Uno tra halfDayoneDayoneWeekoneMonththreeMonthssixMonthsoneYear
  • number_type enum body Facoltativo

    Omettilo per usare il valore predefinito della route.

    Uno tra voipnon_voip
  • Idempotency-Key string header Obbligatorio

    Un UUID, nuovo per ogni acquisto, riutilizzato nei tentativi successivi.

Restituisce

Il nuovo oggetto numero in data; meta.charged, meta.currency, meta.wallet_balance_after.

Errori
  • 422insufficient_fundsIl saldo del wallet non copre il prezzo.
  • 422out_of_stockEsaurito dopo la tua verifica di disponibilità.
  • 422invalid_durationDurata non venduta per questo paese/tipo.
  • 403kyc_requiredPrima è necessaria la verifica dell'identità. Nessun addebito.
  • 503purchases_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"}'
Risposta
{
  "success": true,
  "data": {
    "id": 1482,
    "phone_number": "+14035551234",
    "country_code": "US",
    "country_name": "United States",
    "number_type": "voip",
    "status": "active",
    "purchase_date": "2026-05-13T17:42:09Z",
    "expire_date": "2026-06-13T17:42:09Z"
  },
  "meta": {
    "charged": 4.99,
    "currency": "USD",
    "wallet_balance_after": 119.51
  }
}
POST /v1/numbers/{id}/renew 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
  • id integer path Obbligatorio

    Id del numero da GET /numbers.

  • package enum body Facoltativo

    Durata del rinnovo. Predefinito oneMonth. (duration è accettato come alias legacy.)

    Uno tra oneMonththreeMonthssixMonthsoneYear
  • Idempotency-Key string header Obbligatorio

    Un UUID, nuovo per ogni rinnovo, riutilizzato nei tentativi successivi.

Restituisce

L'oggetto numero aggiornato in data; meta.charged, meta.currency, meta.wallet_balance_after.

Errori
  • 404Non è un numero del tuo account.
  • 422insufficient_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"}'
Risposta
{
  "success": true,
  "data": {
    "id": 1482,
    "phone_number": "+14035551234",
    "country_code": "US",
    "country_name": "United States",
    "number_type": "voip",
    "status": "active",
    "purchase_date": "2026-05-13T17:42:09Z",
    "expire_date": "2026-09-13T17:42:09Z"
  },
  "meta": {
    "charged": 12.99,
    "currency": "USD",
    "wallet_balance_after": 106.52
  }
}
POST /v1/numbers/{id}/cancel 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
  • id integer path Obbligatorio

    Id del numero da GET /numbers.

  • Idempotency-Key string header Obbligatorio

    Un UUID, riutilizzato nei tentativi successivi.

Restituisce

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)"
Risposta
{
  "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
  • idinteger

    Id del messaggio.

  • fromstring

    Mittente: un numero di telefono o un nome come WhatsApp.

  • bodystring

    Il testo completo del messaggio.

  • received_atstring

    ISO 8601, UTC.

Alias deprecati ancora inviati: sender (= from) e message (= body).

oggetto
{
  "id": 9912,
  "from": "+18005550199",
  "body": "Your code is 432901",
  "received_at": "2026-05-13T17:43:14Z"
}
GET /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
  • id integer path Obbligatorio

    Id del numero da GET /numbers.

Restituisce

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"
Risposta
{
  "success": true,
  "data": {
    "number": {
      "id": 1482,
      "phone_number": "+14035551234",
      "country_code": "US",
      "country_name": "United States",
      "number_type": "voip",
      "status": "active",
      "purchase_date": "2026-05-13T17:42:09Z",
      "expire_date": "2026-06-13T17:42:09Z"
    },
    "messages": [
      {
        "id": 9912,
        "from": "+18005550199",
        "body": "Your code is 432901",
        "received_at": "2026-05-13T17:43:14Z"
      }
    ]
  },
  "meta": { "count": 1 }
}
GET /v1/receive-sms

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
  • phoneNumber string query Obbligatorio

    E.164 o solo cifre, ad es. +14035551234. Codifica il + nell'URL.

  • limit integer query Facoltativo

    Dimensione pagina 1-100. Predefinito 50.

  • cursor string query Facoltativo

    meta.nextCursor della pagina precedente.

Campi della risposta
  • data.messages[].idinteger

    Id del messaggio.

  • data.messages[].fromstring

    Mittente.

  • data.messages[].tostring

    Il tuo numero.

  • data.messages[].messagestring

    Il testo completo.

  • data.messages[].receivedAtstring

    ISO 8601.

  • meta.hasMore / nextCursorboolean / string | null

    Passa nextCursor come cursor per la pagina successiva.

Errori
  • 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"
Risposta
{
  "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 | null

    L'indirizzo, oppure null prima dell'attivazione.

  • statusenum

    active o none.

  • unread_countinteger

    Email non lette.

  • created_atstring | null

    Quando l'indirizzo è stato attivato.

  • eligibleboolean

    True quando il numero può attivare subito un indirizzo.

  • linked_numberstring

    Il numero di telefono a cui appartiene.

  • domainstring

    privnum.com

  • suggestionsstring[]

    Suggerimenti di nomi finché il numero è idoneo.

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

Ottieni l'email privata

L'indirizzo di un numero oppure, prima dell'attivazione, se può averne uno e alcuni suggerimenti di nomi.

Parametri
  • id integer path Obbligatorio

    Id del numero da GET /numbers.

Restituisce

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"
Risposta
{
  "success": true,
  "data": {
    "address": null,
    "status": "none",
    "unread_count": 0,
    "created_at": null,
    "eligible": true,
    "linked_number": "+14035551234",
    "domain": "privnum.com",
    "suggestions": ["alex.smith", "alex.smith42"]
  }
}
GET /v1/numbers/{id}/private-email/availability

Verifica un nome

Verifica in tempo reale che un nome sia valido e libero prima di attivarlo.

Parametri
  • id integer path Obbligatorio

    Id del numero da GET /numbers.

  • local_part string query Obbligatorio

    La parte prima di @: 3-64 lettere, numeri, punti, trattini o trattini bassi.

Campi della risposta
  • availableboolean

    True quando puoi attivarlo.

  • reasonenum | null

    too_short, too_long, invalid, reserved o taken.

Errori
  • 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"
Risposta
{
  "success": true,
  "data": {
    "local_part": "alex.smith",
    "address": "[email protected]",
    "available": true,
    "reason": null,
    "message": "Available"
  }
}
POST /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
  • id integer path Obbligatorio

    Id del numero da GET /numbers.

  • local_part string body Obbligatorio

    Il nome che hai verificato.

Restituisce

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"}'
Risposta
{
  "success": true,
  "data": {
    "address": "[email protected]",
    "status": "active",
    "unread_count": 0,
    "created_at": "2026-07-03T10:15:00+00:00",
    "eligible": false,
    "linked_number": "+14035551234",
    "domain": "privnum.com",
    "suggestions": []
  }
}
GET /v1/numbers/{id}/private-email/inbox

Elenca le email

Riepiloghi delle email, dalle più recenti, con paginazione a pagine e il numero di non lette al livello principale.

Parametri
  • id integer path Obbligatorio

    Id del numero da GET /numbers.

  • page integer query Facoltativo

    Numero di pagina. Predefinito 1.

  • per_page integer query Facoltativo

    1-100. Predefinito 25.

Campi della risposta
  • data[]array

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

  • metaobject

    current_page, per_page, total, last_page.

  • unread_countinteger

    Al livello principale, accanto a data.

Errori
  • 404Non è un tuo numero, oppure non ha ancora un indirizzo.
  • 404private_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"
Risposta
{
  "success": true,
  "data": [
    {
      "id": 77,
      "from_email": "[email protected]",
      "from_name": "Example Billing",
      "subject": "Your receipt",
      "preview": "Thanks for your order…",
      "attachment_count": 1,
      "is_read": false,
      "received_at": "2026-07-04T08:01:12+00:00"
    }
  ],
  "meta": { "current_page": 1, "per_page": 25, "total": 1, "last_page": 1 },
  "unread_count": 1
}
GET /v1/numbers/{id}/private-email/inbox/{messageId}/body

Leggi un'email

L'email completa (HTML e testo) con l'elenco degli allegati. Leggerla la segna come letta.

Parametri
  • id integer path Obbligatorio

    Id del numero da GET /numbers.

  • messageId integer path Obbligatorio

    Id dell'email dall'elenco della casella.

Errori
  • 404Non è un tuo numero, oppure non ha ancora un indirizzo.
  • 404private_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"
Risposta
{
  "success": true,
  "data": {
    "id": 77,
    "subject": "Your receipt",
    "from_email": "[email protected]",
    "from_name": "Example Billing",
    "received_at": "2026-07-04T08:01:12+00:00",
    "html": "<p>Thanks for your order…</p>",
    "text": "Thanks for your order…",
    "attachments": [
      { "index": 0, "filename": "receipt.pdf", "content_type": "application/pdf", "size_bytes": 48211 }
    ]
  }
}
GET /v1/numbers/{id}/private-email/inbox/{messageId}/attachments/{index}

Scarica un allegato

Il file originale, con il proprio Content-Type e nome file. index proviene da attachments[] dell'email.

Parametri
  • id integer path Obbligatorio

    Id del numero da GET /numbers.

  • messageId integer path Obbligatorio

    Id dell'email dall'elenco della casella.

  • index integer path Obbligatorio

    attachments[].index da Leggi un'email.

Errori
  • 404Non è un tuo numero, oppure non ha ancora un indirizzo.
  • 404private_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
Risposta
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename=receipt.pdf

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

Elimina un'email

Elimina l'email e i suoi allegati.

Parametri
  • id integer path Obbligatorio

    Id del numero da GET /numbers.

  • messageId integer path Obbligatorio

    Id dell'email dall'elenco della casella.

Errori
  • 404Non è un tuo numero, oppure non ha ancora un indirizzo.
  • 404private_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"
Risposta
{
  "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.

Endpoint
Endpoint MCP · HTTP streamable
https://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

StrumentoCosa faRichiede "Consenti acquisti"
get-balanceRecupera il saldo del portafoglio e la valuta di fatturazione dell'account autenticato.No
get-pricingRestituisce il listino prezzi attivo per tutti i paesi o per un singolo codice paese ISO.No
get-inventoryControlla la disponibilità dell'inventario in tempo reale per un paese, una durata e un tipo di numero facoltativo.No
purchase-numberAcquista un numero privato per l'account autenticato usando i fondi del portafoglio.Sì
list-active-numbersRestituisce i numeri dell'account autenticato, con filtro facoltativo per stato.No
check-smsRecupera i messaggi SMS di un numero acquistato, tramite ID, di proprietà dell'account autenticato.No
renew-numberRinnova un numero acquistato tramite ID, con un pacchetto di durata facoltativo.Sì
cancel-numberAnnulla 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.

  1. Fai clic su Aggiungi a Claude. Claude si apre con Temp Number e il suo URL già compilati. Fai clic su Aggiungi.
  2. Fai clic su Connetti, accedi a Temp Number, scegli se Claude può effettuare acquisti e fai clic su Consenti.
  3. In qualsiasi chat, apri il menu + → Connettori e attiva Temp Number. Prova: "Quanto costa un numero USA per un mese?"
Team ed Enterprise: un proprietario aggiunge il connettore una sola volta da Impostazioni organizzazione → Connettori. Ogni membro accede poi con il proprio account Temp Number, così ognuno spende dal proprio wallet.

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.

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.

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

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

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

Task: <describe what you want to build - e.g. "buy a US number, wait for the verification SMS, then cancel it if it never arrives">.
https://temp-number.com/developers/llms.txt è 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.

Accedi per iniziare