Temp Number API – Telefonnummern, SMS & OTP
Stellen Sie virtuelle Telefonnummern bereit, empfangen Sie SMS in Echtzeit und automatisieren Sie die OTP-Verifizierung – über eine übersichtliche REST API oder direkt aus Ihrem KI-Assistenten.
https://api.temp-number.com/v1
Startseite / Entwickler
Einführung
Die Temp Number API ist um vorhersehbare Ressourcen aufgebaut, verwendet Standard-HTTP-Verben und liefert jede Antwort als JSON. Ein Schlüssel gewährt Lese- und Schreibzugriff nur auf Ihr Konto – kontoübergreifenden Zugriff gibt es nicht.
Schnellstart
Von null bis zum Verifizierungscode. Wählen Sie Ihre Sprache einmal – alle Beispiele auf der Seite folgen ihr.
-
API-Schlüssel erstellen
Erstellen Sie unter Dashboard → API-Zugang einen Schlüssel. Er wird nur einmal angezeigt: Speichern Sie ihn als Umgebungsvariable
TEMP_NUMBER_API_KEY. -
Guthaben prüfen
Jeder Aufruf enthält Ihren Schlüssel im Authorization-Header. Beginnen Sie mit etwas Harmlosem: Ihrem Guthaben.
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(); -
Land wählen und Bestand prüfen
GET /pricing listet jedes Land mit dem genauen Preis pro Laufzeit. Prüfen Sie dann den Bestand für das gewünschte Land.
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(); -
Nummer kaufen
Senden Sie bei jedem Kauf einen neuen Idempotency-Key. Bricht die Verbindung ab, wiederholen Sie mit demselben Schlüssel: Ihnen wird nie doppelt berechnet. Bewahren Sie data.id aus der Antwort auf.
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(); -
SMS lesen
Fragen Sie die Nummer alle paar Sekunden ab, bis die Nachricht eintrifft. Sie erhalten den Rohtext; den Code extrahieren Sie selbst.
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(); -
Keine SMS? Gegen Erstattung stornieren
Zwischen 15 und 120 Minuten nach dem Kauf kann eine Nummer, die keine SMS empfangen hat, gegen volle Erstattung auf Ihr Guthaben storniert werden.
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();
Authentifizierung
Senden Sie Ihren API-Schlüssel bei jeder Anfrage im Standard-Header Authorization:
Authorization: Bearer YOUR_API_KEY
- Erstellen Sie Schlüssel unter API-Zugang. Ein Schlüssel wird nur einmal vollständig angezeigt, bei der Erstellung.
- Verwenden Sie einen Schlüssel pro Integration, damit Sie einen widerrufen können, ohne die anderen zu beeinträchtigen. Eine Passwortänderung widerruft alle Schlüssel.
- Ein fehlender, fehlerhafter oder widerrufener Schlüssel ergibt
401. Ein Konto mit unbestätigter E-Mail-Adresse oder ein gesperrtes Konto ergibt403mitcodeemail_unverifiedbzw.account_suspended. - REST-Schlüssel funktionieren nur auf
/v1. Der MCP-Server nutzt eine eigene Anmeldung oder MCP-Schlüssel – siehe MCP-Server.
Basis-URL & Versionierung
Alle Endpunkte liegen unter dem dauerhaften Präfix /v1:
https://api.temp-number.com/v1
Erweiternde Änderungen – neue Felder, Endpunkte oder optionale Parameter – erscheinen ohne Versionssprung, ignorieren Sie also Felder, die Sie nicht kennen. Eine inkompatible Änderung würde unter /v2 erscheinen; Ihre Integration wird nie stillschweigend umgestellt. Der maschinenlesbare Vertrag ist die OpenAPI-Spezifikation.
Anfragen & Antworten
- Senden Sie JSON-Bodys mit
Content-Type: application/jsonund bei jeder AnfrageAccept: application/json. - Erfolg:
{ "success": true, "data": …, "meta": {…} }.metaenthält Zähler, Paginierung und Geldbeträge. - Fehler:
{ "success": false, "message": "…", "code": "…" }. Verzweigen Sie anhand voncode; die Meldung ist für Menschen gedacht. Siehe Fehler. - Zeitangaben erfolgen im ISO-8601-Format. Beträge sind in USD mit zwei Nachkommastellen angegeben – immer der Preis, den Sie zahlen.
- Einige Objekte enthalten für bestehende Integrationen noch ältere Feldnamen (in der Referenz als veraltet markiert). Neuer Code sollte sie ignorieren.
Fehler
Fehler verwenden Standard-HTTP-Statuscodes. Geschäftsfehler enthalten einen stabilen, maschinenlesbaren code; manche enthalten details mit weiterem Kontext.
{
"success": false,
"message": "Insufficient wallet balance.",
"code": "insufficient_funds"
}
{
"message": "The country code field is required.",
"errors": {
"country_code": ["The country code field is required."]
}
}
| Status | code | Bedeutung | Was zu tun ist |
|---|---|---|---|
| 400 | - | Der Idempotency-Key-Header fehlt oder ist fehlerhaft bei Kauf, Verlängerung oder Stornierung. Body: {"error": "Missing Idempotency-Key header."} | Senden Sie eine UUID im Idempotency-Key. |
| 401 | - | Kein Bearer-Token, ein fehlerhaftes oder ein widerrufener Schlüssel. | Prüfen Sie den Authorization-Header; erstellen Sie einen neuen Schlüssel, falls er widerrufen wurde. |
| 403 | email_unverified |
Das Konto hat seine E-Mail-Adresse noch nicht bestätigt. | Bestätigen Sie die E-Mail-Adresse auf der Website und versuchen Sie es dann erneut. |
| 403 | account_suspended |
Das Konto ist gesperrt. | Wenden Sie sich an den Support. |
| 403 | kyc_required |
Das Konto muss seine Identität bestätigen, bevor es neue Nummern kaufen kann. Es wurde nichts berechnet; Verlängerungen funktionieren weiterhin. | Schließen Sie die Identitätsprüfung in den Kontoeinstellungen ab und versuchen Sie es dann erneut. |
| 403 | - | Der Schlüssel hat keinen API-Zugriff (zum Beispiel ein MCP-Schlüssel), oder GET /receive-sms wurde nach einer Nummer eines anderen Kontos gefragt. | Verwenden Sie einen REST-API-Schlüssel; fragen Sie nur Ihre eigenen Nummern ab. |
| 404 | - | Die Nummer, Nachricht oder das Land gehört nicht zu Ihrem Konto oder ist derzeit nicht im Angebot. IDs anderer Konten antworten ebenfalls mit 404. | Erneut auflisten mit GET /numbers oder GET /pricing. |
| 404 | private_email_closed |
Das private Postfach ist geschlossen, weil seine Nummer storniert oder erstattet wurde. | Nichts zu wiederholen. |
| 409 | - | Der Idempotency-Key wurde bereits mit einem anderen Body verwendet, oder die erste Anfrage damit läuft noch. | Verwenden Sie für eine neue Anfrage einen neuen Schlüssel; für die laufende warten Sie und versuchen es erneut. |
| 422 | insufficient_funds |
Das Guthaben deckt den Preis nicht. | Laden Sie das Guthaben auf und versuchen Sie es erneut. |
| 422 | out_of_stock |
Der Markt war zwischen Ihrer Preisprüfung und dem Kauf ausverkauft. | Prüfen Sie GET /inventory erneut und wählen Sie eine andere Laufzeit oder einen anderen Typ. |
| 422 | invalid_duration |
Die Laufzeit wird für dieses Land und diesen Nummerntyp nicht angeboten. | Rufen Sie GET /pricing/{countryCode} erneut ab. |
| 422 | - | Validierung fehlgeschlagen (ein `errors`-Objekt nennt jedes Feld) oder eine Regel hat die Aktion abgelehnt, etwa eine Stornierung außerhalb des Erstattungsfensters. | Lesen Sie `message`; korrigieren Sie die Anfrage, statt sie zu wiederholen. |
| 429 | - | Rate-Limit erreicht. | Warten Sie auf den Retry-After-Header und versuchen Sie es dann mit Backoff erneut. |
| 503 | purchases_paused |
Neue Käufe sind plattformweit pausiert. Es wurde nichts berechnet; Verlängerungen und Stornierungen funktionieren weiterhin. | Nach Retry-After (60 s) erneut versuchen. |
| 5xx | - | Bei uns ist etwas fehlgeschlagen. | Wiederholen Sie mit DEMSELBEN Idempotency-Key – Ihnen wird nie doppelt berechnet. |
Rate Limits
Limits gelten pro Schlüssel, und für Aufrufe, die Geld bewegen, gilt zusätzlich ein strengeres Limit pro Konto:
| Gilt für | Limit | Gezählt |
|---|---|---|
| Alle Endpunkte | 60 / Minute | pro API-Schlüssel |
| Kaufen, verlängern, stornieren | 10 / Minute | pro Konto, zusätzlich zu den obigen Limits |
| GET /receive-sms | 60 / Minute | pro API-Schlüssel |
| GET /receive-sms | 30 / Minute | pro API-Schlüssel und Telefonnummer |
| GET /receive-sms | 30 / Minute | pro IP-Adresse |
Bei Überschreitung eines Limits erhalten Sie 429 mit einem Retry-After-Header (Sekunden). Warten Sie mindestens so lange und wiederholen Sie dann mit Backoff und Jitter. Antworten enthalten außerdem X-RateLimit-Limit und X-RateLimit-Remaining.
Idempotenz
POST /numbers/buy, /renew und /cancel erfordern einen Idempotency-Key-Header: eine UUID, die Sie für jede neue Aktion erzeugen. Bricht die Verbindung ab, senden Sie dieselbe Anfrage mit demselben Schlüssel – Sie erhalten die ursprüngliche Antwort zurück (gekennzeichnet mit X-Idempotency-Replayed: true) und werden nie doppelt belastet.
- Fehlender Schlüssel:
400. Schlüssel bestehen aus bis zu 128 Zeichen aus Buchstaben, Ziffern und- _ . : - Gleicher Schlüssel mit anderem Body:
409. Gleicher Schlüssel, während die erste Anfrage noch läuft:409– warten Sie kurz und versuchen Sie es erneut. - Schlüssel werden pro Konto und Endpunkt gespeichert. Verwenden Sie einen Schlüssel nie für einen anderen Kauf erneut.
Paginierung
GET /receive-sms verwendet Cursor-Paginierung, neueste zuerst. Lesen Sie meta.hasMore; solange es true ist, senden Sie meta.nextCursor als cursor mit derselben phoneNumber zurück. Cursor sind opak – erstellen oder bearbeiten Sie sie nicht selbst.
GET https://api.temp-number.com/v1/receive-sms?phoneNumber=%2B14035551234&limit=50&cursor=eyJkYXRlIjoiMjAyNi0wNS0xMyJ9
Naturgemäß kleine Listen (/numbers, /pricing) geben alles in einer Antwort zurück; der private Posteingang verwendet page und per_page.
Zulässige Nutzung
Die API ist für Entwickler gebaut: Verifizierungs- und OTP-Abläufe, automatisiertes Onboarding, QA und Systemtests sowie jedes Produkt, das eingehende SMS oder Telefonnummern in großem Umfang benötigt.
- Nutzen Sie es ausschließlich für legitime Verifizierung, Entwicklung und Tests.
- Kein Betrug, Spam oder Täuschung. Werden Nummern für Betrug oder andere missbräuchliche Aktivitäten genutzt, wird das Konto sofort und ohne Vorankündigung gesperrt, zugehörige Nummern werden storniert und es besteht kein Anspruch auf Erstattung.
- Nicht für regulierte oder identitätsgebundene Konten. Unsere geteilten, temporären Nummern unterstützen keine SMS-Verifizierung für Banken, Zahlungsdienste, Kryptowährungen, Behörden oder andere Dienste, die Ihre rechtliche Identität prüfen (KYC/AML) – verwenden Sie dafür Ihre eigene private Mobilnummer.
API-Referenz
Jeder aktive /v1-Endpunkt. Anfragen stehen rechts in Ihrer Sprache; Antworten zeigen echte Strukturen.
Konto
Lesen Sie Ihr Guthaben und die Abrechnungswährung.
/v1/account
Guthaben abrufen
Gibt das verfügbare Guthaben und seine Währung zurück. Prüfen Sie es vor einem Kauf, damit Sie früh mit einem klaren Hinweis zum Aufladen abbrechen können.
Antwortfelder-
balancenumberVerfügbares Guthaben.
-
currencystringAbrechnungswährung, USD.
- 401Fehlender oder ungültiger Schlüssel.
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"
}
Preise & Bestand
Durchsuchen Sie aktuelle Märkte, den genauen Preis pro Laufzeit und den Bestand in Echtzeit.
Das Länderpreis-Objekt
Ein Land und jedes Paket, das Sie dort kaufen können. price ist der Endbetrag, mit dem Ihr Guthaben belastet wird; Einkaufskosten werden nie offengelegt.
Felder-
country_codestringISO-3166-1-Alpha-2-Code, z. B. US.
-
country_namestringAnzeigename.
-
packages[].number_typeenumvoip oder non_voip.
-
packages[].durationenumDer Schlüssel, den Sie zum Kaufen senden: halfDay, oneDay, oneWeek, oneMonth, threeMonths, sixMonths oder oneYear. Jedes Land bietet eigene Laufzeiten an.
-
packages[].duration_labelstringLesbare Bezeichnung, z. B. "1 Month".
-
packages[].pricenumberEndpreis in USD.
-
packages[].original_pricenumber | nullDer Preis vor einem Rabatt, falls einer gilt.
-
packages[].updated_atnullReserviert.
{
"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
Preise für alle Länder auflisten
Der vollständige Live-Katalog: eine Liste von Länderpreis-Objekten. Das Feld price ist der endgültige Preis für Nutzer in USD, genau der Betrag, mit dem Ihr Guthaben belastet wird.
RückgabeEine Liste von Länderpreis-Objekten in data, mit meta.count.
Fehler- 401Fehlender oder ungültiger Schlüssel.
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}
Preise für ein Land abrufen
Aktuelle Preise für ein einzelnes Land. Ein 404 bedeutet, dass das Land gerade keine aktive Route hat: Behandeln Sie es als vorübergehend „nicht vorrätig“, nicht als „nie im Angebot“.
Parameter-
countryCodestring path ErforderlichISO-3166-1-Alpha-2-Ländercode, z. B. US, GB, CA.
Ein Länderpreis-Objekt in data.
Fehler- 404Derzeit keine aktive Route für dieses Land.
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
Bestand prüfen
Echtzeit-Bestand für ein Land und eine Laufzeit, sodass Sie einen Kaufen-Button deaktivieren können, bevor jemand klickt. Lassen Sie number_type weg, um alle Typen nebeneinander in types[] zu erhalten. Ein grünes Ergebnis ist ein starkes Signal, aber der Kauf selbst ist die endgültige Prüfung.
Parameter-
country_codestring query ErforderlichISO-3166-1-Alpha-2-Ländercode.
-
durationenum query OptionalEin Laufzeitschlüssel aus GET /pricing/{countryCode}. Weglassen für den Standard der Route.
Einer vonhalfDayoneDayoneWeekoneMonththreeMonthssixMonthsoneYear -
number_typeenum query OptionalDie Prüfung auf einen Typ beschränken. Weglassen, um alle Typen zu sehen.
Einer vonvoipnon_voip
-
stockinteger | nullVerfügbare Nummern (summiert über types[], wenn number_type weggelassen wird).
-
availablebooleanTrue, wenn mindestens eine Nummer gekauft werden kann.
-
statusstringLesbare Bezeichnung: In Stock, Out of Stock, Coming Soon…
-
types[]arrayNur wenn number_type weggelassen wird: number_type, stock, available, status pro Typ, den der Markt verkauft.
- 422Für diese Auswahl ist nichts im Angebot; details enthält die Bestandsfelder.
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" }
]
}
}
Nummern
Ihre privaten Nummern auflisten, kaufen, verlängern und stornieren. Aufrufe, die Geld bewegen, sind idempotent und sicher wiederholbar.
Das Nummern-Objekt
Eine Nummer in Ihrem Konto. Kaufen, Verlängern und Stornieren liefern zudem eine Geldübersicht in meta: charged (oder refunded), currency und wallet_balance_after.
Felder-
idintegerVerwenden Sie sie in /numbers/{id}/…-Aufrufen. Webhooks senden sie als number.rentalId.
-
phone_numberstringE.164, z. B. +14035551234.
-
country_codestring | nullISO 3166-1 Alpha-2.
-
country_namestringAnzeigename.
-
number_typeenumvoip oder non_voip.
-
statusenumactive, expired, cancelled oder refunded.
-
purchase_datestringISO 8601, UTC.
-
expire_datestringISO 8601, UTC. Danach empfängt die Nummer keine SMS mehr und kann nicht verlängert werden.
Veraltete Aliase, die für ältere Integrationen weiterhin gesendet werden: country, provider, purchased_at und expires_at (Epoch-Millisekunden). Bauen Sie nicht darauf auf.
{
"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
Ihre Nummern auflisten
Alle Nummern in Ihrem Konto, neueste zuerst. Verwenden Sie status=expiring_soon (aktive Nummern innerhalb von 10 Tagen vor Ablauf), um Verlängerungserinnerungen auszulösen.
Parameter-
statusenum query OptionalFilter für den Lebenszyklus. Standard: all.
Einer vonallactiveexpiring_soonexpiredcancelled
Eine Liste von Nummern-Objekten in data; meta.count und meta.status.
Fehler- 401Fehlender oder ungültiger Schlüssel.
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 erforderlich Nummer kaufen
Weist eine neue private Nummer zu und belastet Ihr Guthaben in einem atomaren Schritt. Schlägt die Bereitstellung nach der Belastung fehl, wird die Belastung rückgängig gemacht: Sie zahlen nie, ohne etwas zu erhalten. Die Antwort zeigt den belasteten Betrag und Ihr Guthaben danach.
Parameter-
country_codestring body ErforderlichEin Land aus GET /pricing.
-
durationenum body ErforderlichEin Laufzeitschlüssel aus packages[] dieses Landes – jedes Land bietet eigene Laufzeiten an.
Einer vonhalfDayoneDayoneWeekoneMonththreeMonthssixMonthsoneYear -
number_typeenum body OptionalWeglassen, um den Standard der Route zu verwenden.
Einer vonvoipnon_voip -
Idempotency-Keystring header ErforderlichEine UUID, neu für jeden Kauf, bei Wiederholungen wiederverwendet.
Das neue Nummern-Objekt in data; meta.charged, meta.currency, meta.wallet_balance_after.
Fehler- 422
insufficient_fundsDas Guthaben deckt den Preis nicht. - 422
out_of_stockSeit Ihrer Bestandsprüfung ausverkauft. - 422
invalid_durationLaufzeit für dieses Land/diesen Typ nicht im Angebot. - 403
kyc_requiredZuerst ist eine Identitätsprüfung erforderlich. Es wurde nichts berechnet. - 503
purchases_pausedKäufe plattformweit pausiert. 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 erforderlich Nummer verlängern
Verlängert eine Nummer um das gewählte Paket. Die neue Laufzeit wird an das aktuelle Ablaufdatum angehängt, sodass eine frühe Verlängerung nichts kostet. Der Preis ist der aktuelle Website-Tarif und wird bei uns berechnet. Abgelaufene Nummern können nicht verlängert werden: Kaufen Sie eine neue.
Parameter-
idinteger path ErforderlichNummern-ID aus GET /numbers.
-
packageenum body OptionalVerlängerungsdauer. Standard oneMonth. (duration wird als veralteter Alias akzeptiert.)
Einer vononeMonththreeMonthssixMonthsoneYear -
Idempotency-Keystring header ErforderlichEine UUID, neu für jede Verlängerung, bei Wiederholungen wiederverwendet.
Das aktualisierte Nummern-Objekt in data; meta.charged, meta.currency, meta.wallet_balance_after.
Fehler- 404Keine Nummer in Ihrem Konto.
- 422
insufficient_fundsDas Guthaben deckt die Verlängerung nicht. - 422Abgelaufen, storniert oder nicht verlängerbar.
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 erforderlich Nummer gegen Erstattung stornieren
Gibt eine Nummer frei und erstattet ihren vollen Preis auf Ihr Guthaben. Nur zwischen 15 und 120 Minuten nach dem Kauf erlaubt, solange die Nummer aktiv ist und noch keine SMS empfangen hat. Außerhalb dieser Regeln wird der Aufruf mit 422 abgelehnt und nichts ändert sich; ist es zu früh, gibt details.seconds_until_open an, wie lange Sie warten müssen.
Parameter-
idinteger path ErforderlichNummern-ID aus GET /numbers.
-
Idempotency-Keystring header ErforderlichEine UUID, bei Wiederholungen wiederverwendet.
Das Nummern-Objekt (Status cancelled) in data; meta.refunded, meta.currency, meta.wallet_balance_after.
Fehler- 404Keine Nummer in Ihrem Konto.
- 422Zu früh (unter 15 Min.), zu spät (über 120 Min.), bereits SMS empfangen oder nicht aktiv.
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
Lesen Sie die SMS, die Ihre Nummern empfangen. Sie erhalten den Rohtext; das Extrahieren eines Codes liegt bei Ihnen.
Das SMS-Nachrichtenobjekt
Eine empfangene SMS, wie von GET /numbers/{id}/sms zurückgegeben. (GET /receive-sms verwendet eine camelCase-Variante, die bei diesem Endpunkt gezeigt wird.)
Felder-
idintegerNachrichten-ID.
-
fromstringAbsender: eine Telefonnummer oder ein Name wie WhatsApp.
-
bodystringDer vollständige Nachrichtentext.
-
received_atstringISO 8601, UTC.
Veraltete Aliase, die weiterhin gesendet werden: sender (= from) und message (= body).
{
"id": 9912,
"from": "+18005550199",
"body": "Your code is 432901",
"received_at": "2026-05-13T17:43:14Z"
}
/v1/numbers/{id}/sms
Eine Nummer und ihre SMS abrufen
Eine Nummer zusammen mit jeder SMS, die sie empfangen hat, neueste zuerst. Ideal für eine Detailansicht einer Nummer und zum Abfragen einer einzelnen Nummer, während Sie auf einen Code warten. IDs, die nicht Ihnen gehören, antworten mit 404.
Parameter-
idinteger path ErforderlichNummern-ID aus GET /numbers.
data.number (ein Nummernobjekt) und data.messages (SMS-Nachrichtenobjekte); meta.count.
Fehler- 404Keine Nummer in Ihrem Konto.
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
SMS per Telefonnummer empfangen
Cursor-paginierte SMS für eine Nummer in Ihrem Besitz, adressiert über ihre Telefonnummer statt ihrer ID. Ideal für Postfächer mit hohem Aufkommen. Eine Nummer, die nicht Ihnen gehört, antwortet mit 403.
Parameter-
phoneNumberstring query ErforderlichE.164 oder nur Ziffern, z. B. +14035551234. Kodieren Sie das + in der URL.
-
limitinteger query OptionalSeitengröße 1–100. Standard 50.
-
cursorstring query Optionalmeta.nextCursor von der vorherigen Seite.
-
data.messages[].idintegerNachrichten-ID.
-
data.messages[].fromstringAbsender.
-
data.messages[].tostringIhre Nummer.
-
data.messages[].messagestringDer vollständige Text.
-
data.messages[].receivedAtstringISO 8601.
-
meta.hasMore / nextCursorboolean / string | nullÜbergeben Sie nextCursor als cursor für die nächste Seite.
- 403Die Nummer gehört nicht zu Ihrem Konto.
- 422phoneNumber fehlt oder ist ungültig.
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"
}
}
Private E-Mail
Ein kostenloses Postfach [email protected] nur zum Empfangen für jede private Nummer. Eine Adresse pro Nummer.
Das Private-E-Mail-Objekt
Das Postfach, das zu einer Nummer gehört.
Felder-
addressstring | nullDie Adresse oder null, bevor sie beansprucht wurde.
-
statusenumactive oder none.
-
unread_countintegerUngelesene E-Mails.
-
created_atstring | nullWann die Adresse beansprucht wurde.
-
eligiblebooleanTrue, wenn die Nummer jetzt eine Adresse beanspruchen kann.
-
linked_numberstringDie Telefonnummer, zu der sie gehört.
-
domainstringprivnum.com
-
suggestionsstring[]Namensvorschläge, solange berechtigt.
{
"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
Private E-Mail abrufen
Die Adresse einer Nummer oder, bevor eine beansprucht wurde, ob sie eine haben kann, plus einige Namensvorschläge.
Parameter-
idinteger path ErforderlichNummern-ID aus GET /numbers.
Ein Private-E-Mail-Objekt in data.
Fehler- 404Keine Nummer in Ihrem Konto.
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
Namen prüfen
Live-Prüfung, ob ein Name gültig und frei ist, bevor Sie ihn beanspruchen.
Parameter-
idinteger path ErforderlichNummern-ID aus GET /numbers.
-
local_partstring query ErforderlichDer Teil vor dem @: 3–64 Buchstaben, Zahlen, Punkte, Bindestriche oder Unterstriche.
-
availablebooleanTrue, wenn Sie ihn beanspruchen können.
-
reasonenum | nulltoo_short, too_long, invalid, reserved oder taken.
- 404Keine Nummer in Ihrem Konto.
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
Adresse beanspruchen
Gibt einer aktiven Nummer ihre Adresse. Kostenlos, eine pro Nummer, und eine beanspruchte Adresse wird nie an jemand anderen vergeben.
Parameter-
idinteger path ErforderlichNummern-ID aus GET /numbers.
-
local_partstring body ErforderlichDer geprüfte Name.
Das Private-E-Mail-Objekt in data.
Fehler- 404Nicht Ihre Nummer oder noch keine Adresse.
- 422Name vergeben oder ungültig (details.reason), die Nummer hat bereits eine Adresse oder sie ist nicht aktiv.
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
E-Mails auflisten
E-Mail-Zusammenfassungen, neueste zuerst, mit seitenbasierter Paginierung und der Anzahl ungelesener E-Mails auf oberster Ebene.
Parameter-
idinteger path ErforderlichNummern-ID aus GET /numbers.
-
pageinteger query OptionalSeitennummer. Standard 1.
-
per_pageinteger query Optional1–100. Standard 25.
-
data[]arrayid, from_email, from_name, subject, preview, attachment_count, is_read, received_at.
-
metaobjectcurrent_page, per_page, total, last_page.
-
unread_countintegerOberste Ebene, neben data.
- 404Nicht Ihre Nummer oder noch keine Adresse.
- 404
private_email_closedDie Nummer wurde storniert oder erstattet.
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
E-Mail lesen
Die vollständige E-Mail (HTML und Text) mit ihrer Anhangsliste. Beim Lesen wird sie als gelesen markiert.
Parameter-
idinteger path ErforderlichNummern-ID aus GET /numbers.
-
messageIdinteger path ErforderlichE-Mail-ID aus der Postfachliste.
- 404Nicht Ihre Nummer oder noch keine Adresse.
- 404
private_email_closedDie Nummer wurde storniert oder erstattet.
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}
Anhang herunterladen
Die Rohdatei mit eigenem Content-Type und Dateinamen. index stammt aus attachments[] der E-Mail.
Parameter-
idinteger path ErforderlichNummern-ID aus GET /numbers.
-
messageIdinteger path ErforderlichE-Mail-ID aus der Postfachliste.
-
indexinteger path Erforderlichattachments[].index aus „E-Mail lesen“.
- 404Nicht Ihre Nummer oder noch keine Adresse.
- 404
private_email_closedDie Nummer wurde storniert oder erstattet. - 404Kein Anhang an diesem Index.
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}
E-Mail löschen
Löscht die E-Mail und ihre Anhänge.
Parameter-
idinteger path ErforderlichNummern-ID aus GET /numbers.
-
messageIdinteger path ErforderlichE-Mail-ID aus der Postfachliste.
- 404Nicht Ihre Nummer oder noch keine Adresse.
- 404
private_email_closedDie Nummer wurde storniert oder erstattet.
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
}
KI & MCP
Lassen Sie einen KI-Assistenten direkt Ihr Konto nutzen, oder geben Sie einem Coding-Agenten alles, was er für die Entwicklung mit der API braucht.
MCP-Server
Neben der REST-API betreiben wir einen Model Context Protocol-Server. Verbinden Sie ihn mit Claude, ChatGPT oder Ihrem Editor, und der Assistent kann Preise und Verfügbarkeit prüfen, eine Nummer kaufen und ihre SMS als native Tools lesen – ganz ohne Code auf Ihrer Seite. Neu bei MCP? Beginnen Sie mit der Übersicht zum MCP-Server.
Endpunkthttps://mcp.temp-number.com/mcp
So funktioniert die Anmeldung
- Fügen Sie die URL zu Ihrer KI-App hinzu. Sie werden zu Temp Number weitergeleitet, um sich mit Ihrem eigenen Konto anzumelden (OAuth 2.1 mit PKCE) – kein Schlüssel zum Kopieren.
- Auf dem Zustimmungsbildschirm legen Sie fest, was der Assistent tun darf. Das Lesen von Guthaben, Preisen, Ihren Nummern und deren SMS ist immer enthalten. Käufe erlauben – Kaufen, Verlängern und Stornieren mit Ihrem Guthaben – ist deaktiviert, sofern Sie es nicht ankreuzen.
- Jede Verbindung wird unter Dashboard → MCP-Server → Verbundene Apps aufgeführt, wo Sie sie jederzeit trennen können.
- Lieber einen Schlüssel (CI, Skripte, Headless-Agenten)? Erstellen Sie auf derselben Seite einen MCP-Schlüssel und senden Sie ihn als
Authorization: Bearer <key>. MCP-Schlüssel und REST-API-Schlüssel sind nicht austauschbar.
Tools
| Tool | Was es tut | Erfordert „Käufe erlauben“ |
|---|---|---|
get-balance | Ruft das Guthaben und die Abrechnungswährung des authentifizierten Kontos ab. | Nein |
get-pricing | Gibt den aktuellen Preiskatalog für alle Länder oder einen einzelnen ISO-Ländercode zurück. | Nein |
get-inventory | Prüft die aktuelle Verfügbarkeit für ein Land, eine Laufzeit und optional einen Nummerntyp. | Nein |
purchase-number | Kauft eine private Nummer für das authentifizierte Konto mit Guthaben. | Ja |
list-active-numbers | Gibt die Nummern des authentifizierten Kontos zurück, optional nach Status gefiltert. | Nein |
check-sms | Ruft SMS-Nachrichten für eine gekaufte Nummern-ID ab, die dem authentifizierten Konto gehört. | Nein |
renew-number | Verlängert eine gekaufte Nummer anhand ihrer ID, optional mit einem Laufzeitpaket. | Ja |
cancel-number | Storniert eine gekaufte Nummer anhand ihrer ID und erstattet einen etwaigen berechtigten Betrag auf das Guthaben. | Ja |
Verbinden Sie Ihr KI-Tool
Wählen Sie Ihre App. Die meisten verbinden sich mit einem Klick: Sie melden sich bei Temp Number an, wählen aus, was der Assistent tun darf, und klicken auf Allow.
Claude – claude.ai, Desktop und Mobil
Keine Installation nötig. Funktioniert im Browser, in der Desktop-App und auf dem Smartphone.
- Klicken Sie auf Add to Claude. Claude öffnet sich mit Temp Number und der bereits ausgefüllten URL. Klicken Sie auf Add.
- Klicken Sie auf Connect, melden Sie sich bei Temp Number an, legen Sie fest, ob Claude Käufe tätigen darf, und klicken Sie auf Allow.
- Öffnen Sie in einem beliebigen Chat das Menü + → Connectors und aktivieren Sie Temp Number. Probieren Sie: „Was kostet eine US-Nummer für einen Monat?“
Kein Button? Gehen Sie in Claude zu Customize → Connectors → Add custom connector und fügen Sie den MCP-Endpunkt ein. Organisationen mit der Request-Header-Option von Claude können statt der Anmeldung einen MCP-Schlüssel als Authorization: Bearer <key> senden.
ChatGPT
Erfordert ChatGPT Business, Enterprise oder Edu im Web. Bei Business fügt ein Admin oder Inhaber ihn hinzu.
- Kopieren Sie die Server-URL unten und klicken Sie dann auf ChatGPT öffnen, um zur Seite Plugins zu gelangen. ChatGPT bietet keinen Link, der dies automatisch ausfüllt.
- Klicken Sie auf + → Add custom MCP server. Nennen Sie ihn Temp Number und fügen Sie die URL unter Connection ein.
- Stellen Sie die Authentifizierung auf OAuth, akzeptieren Sie den Risikohinweis und klicken Sie auf Create as a plugin.
- Wenn ChatGPT danach fragt, melden Sie sich bei Temp Number an, legen Sie fest, ob ChatGPT Käufe tätigen darf, und klicken Sie auf Allow.
- Geben Sie in einem neuen Chat @ ein und wählen Sie Temp Number. Probieren Sie: „Was kostet eine US-Nummer für einen Monat?“
https://mcp.temp-number.com/mcp
Claude Code
Fügen Sie den Server einmal hinzu und melden Sie sich dann direkt in Claude Code an.
claude mcp add --transport http temp-number https://mcp.temp-number.com/mcp
- Starten Sie Claude Code und geben Sie
/mcpein. - Wählen Sie temp-number → Authenticate. Ihr Browser öffnet sich: Melden Sie sich an und klicken Sie auf Allow.
Stattdessen einen MCP-Schlüssel verwenden (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
Fügen Sie den Server hinzu und melden Sie sich an. Codex speichert die Sitzung für Sie.
codex mcp add temp-number --url https://mcp.temp-number.com/mcp
codex mcp login temp-number
Stattdessen einen MCP-Schlüssel verwenden (CI / Headless)
In ~/.codex/config.toml. Der Schlüssel wird aus der Umgebung gelesen, daher kann die Datei bedenkenlos geteilt werden.
[mcp_servers.temp-number]
url = "https://mcp.temp-number.com/mcp"
bearer_token_env_var = "TEMPNUMBER_MCP_KEY"
Cursor
Ein Klick, dann melden Sie sich an, wenn Cursor danach fragt.
Oder fügen Sie ihn zu .cursor/mcp.json (oder ~/.cursor/mcp.json) hinzu. Cursor zeigt dann Needs login neben dem Server an: Klicken Sie darauf, melden Sie sich an und klicken Sie auf Allow.
{
"mcpServers": {
"temp-number": {
"url": "https://mcp.temp-number.com/mcp"
}
}
}
Stattdessen einen MCP-Schlüssel verwenden
{
"mcpServers": {
"temp-number": {
"url": "https://mcp.temp-number.com/mcp",
"headers": {
"Authorization": "Bearer ${env:TEMPNUMBER_MCP_KEY}"
}
}
}
}
VS Code (GitHub Copilot)
Ein Klick, dann melden Sie sich an, wenn ein Tool zum ersten Mal ausgeführt wird.
Oder fügen Sie ihn zu .vscode/mcp.json hinzu – beachten Sie, dass der Schlüssel servers lautet, nicht mcpServers.
{
"servers": {
"temp-number": {
"type": "http",
"url": "https://mcp.temp-number.com/mcp"
}
}
}
Stattdessen einen MCP-Schlüssel verwenden
VS Code fragt einmal nach dem Schlüssel und bewahrt ihn in seinem geschützten Speicher auf.
{
"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
}
]
}
Jede andere MCP-App
Windsurf, Zed, LibreChat, Ihr eigener Agent…
- Fügen Sie den MCP-Endpunkt als Remote-Server (Streamable HTTP) hinzu. Apps mit Anmeldeunterstützung finden ihn selbstständig unter
https://mcp.temp-number.com/.well-known/oauth-protected-resourceund öffnen den Zustimmungsbildschirm von Temp Number. - Apps ohne Anmeldeunterstützung können einen MCP-Schlüssel als
Authorization: Bearer <key>senden.
https://mcp.temp-number.com/mcp
llms.txt & Agent-Prompt
Entwickeln Sie mit einem KI-Coding-Assistenten? Geben Sie ihm den folgenden Kontext, und er kann die API in einem Durchgang korrekt integrieren – inklusive Authentifizierung, Idempotenz und Rate-Limits.
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 ist eine stets aktuelle Klartext-Übersicht aller Endpunkte; die OpenAPI-Spezifikation ist der typisierte Vertrag. Beide werden mit der API aktualisiert.Ressourcen
Was sich geändert hat und wo Sie Hilfe erhalten.
Änderungsprotokoll
Nur erweiternde Änderungen – auf /v1 wurde nichts entfernt.
-
NewMCP: Mit Ihrem Temp Number-Konto anmelden
„Add to Claude“ mit einem Klick, dazu ChatGPT, Claude Code, Codex, Cursor und VS Code, ohne einen Schlüssel zu kopieren. Auf dem Zustimmungsbildschirm entscheiden Sie, ob die KI Geld ausgeben darf.
-
DocsEin neues Zuhause für die Dokumentation
Schnellstart, Suche und jedes Beispiel in cURL, Node.js, Python und PHP. Fehler, Rate-Limits und Erstattungen entsprechen jetzt genau der Live-API.
-
Newllms.txt für die gesamte Website
Eine Klartext-Übersicht des Dienstes für KI-Assistenten, mit Link zur agentenfähigen API-Referenz.
-
NewVerbinden Sie Ihr KI-Tool
Einrichtung für Claude Code, Codex, Cursor und VS Code, mit Installationslinks per Klick für Cursor und VS Code.
-
NewOpenAPI-Spezifikation
Der maschinenlesbare Vertrag wird unter https://api.temp-number.com/api.json bereitgestellt.
-
ImprovedObjekte entsprechen der Referenz
Nummern und SMS verwenden ISO-8601-Datumsangaben und from/body. Fehler enthalten einen maschinenlesbaren Code (out_of_stock, insufficient_funds, invalid_duration). /inventory meldet jeden Nummerntyp, wenn Sie number_type weglassen. Die alten Feldnamen funktionieren weiterhin als veraltete Aliase.
-
NewEndpunkte für private E-Mail
Beanspruchen Sie ein kostenloses Postfach [email protected] für eine Nummer, lesen Sie E-Mails und laden Sie Anhänge über die API herunter.
-
NewMCP-Server
KI-Agenten können mit einem MCP-Schlüssel Preise prüfen, Nummern kaufen und SMS lesen – als Tools.
-
LaunchÖffentliche REST-API v1
Konto, Preise, Bestand, der Lebenszyklus der Nummern und SMS, mit Bearer-Token-Authentifizierung.
Support
Kommen Sie nicht weiter, oder haben Sie in dieser Dokumentation etwas gefunden, das nicht dem Verhalten der API entspricht? Kontaktieren Sie uns – mit Endpunkt, Zeitpunkt der Anfrage und Antwort-Body (niemals Ihren API-Schlüssel).
Bereit loszulegen?
Erstellen Sie einen Schlüssel und machen Sie Ihren ersten Aufruf in weniger als einer Minute.