API zur SMS-Verifizierung
Die API zur SMS-Verifizierung besteht aus drei Aufrufen: Nummer kaufen, auf den Code warten, Nummer freigeben. Sie erreicht 517 Dienste in 225 Ländern, Nummern beginnen bei 0,07 €, und eine Aktivierung ohne Empfang wird ohne Support-Ticket erstattet. Schlüssel tragen Scopes, Käufe sind idempotent, und alte handler_api-Clients laufen unverändert weiter.
Die API in einem Block
Aktualisiert am 28.08.2026- Basis-URL
- https://virtualsmsnumbers.com/api/v1
- Authentifizierung
- Bearer-Schlüssel oder X-Api-Key
- Ratenbegrenzung
- 120/min, Spitze 20/s
- Idempotenzfenster
- 24 Stunden
- Automatische Erstattung nach
- 20 Minuten
- Günstigste Aktivierung
- 0,07 €
- Abgedeckte Länder
- 225
- Format
- JSON, Cent, ISO 8601 UTC
Preise und Bestände stammen aus dem Betreiberpool in seinem aktuellen Zustand, nicht aus einer veröffentlichten Preisliste.
Der Ablauf in drei Aufrufen
Alles andere in der Referenz ist optional. Das hier ist der vollständige Verifizierungspfad, und er hat sich seit 2019 nicht geändert.
- 1
POST /activations
Fordern Sie einen Dienst an, und ein Land, falls es Ihnen wichtig ist. Die Antwort enthält die Nummer, den Preis in Cent und den Ablaufzeitpunkt. Senden Sie einen Idempotency-Key, damit eine wiederholte Anfrage keine zweite Nummer kauft, und ein max_price_cents, wenn der Aufrufer automatisiert ist.
- 2
GET /activations/{id}?wait=180
Long Poll. Die Verbindung bleibt offen, bis die Nachricht eintrifft oder das Zeitlimit greift, eine Anfrage ersetzt also eine Schleife, die sonst neunzig machen würde. Der Status kommt als code_received zurück, mit dem ausgelesenen Code neben dem Rohtext, denn Absender formatieren unterschiedlich.
- 3
POST /activations/{id}/complete
Schließen Sie die Aktivierung und geben Sie die Leitung frei. Kam nichts an, tun Sie gar nichts: Das Fenster läuft von selbst ab und das Guthaben wird zurückgebucht. Vorzeitig abbrechen ist derselbe Aufruf unter anderem Namen.
Ein lauffähiges Beispiel
Setzen Sie VSN_KEY und führen Sie es aus. Die auskommentierten Antworten sind die echten Formen, samt der Felder, die Sie speichern wollen.
# 1. Buy a Telegram number in Portugal
-kw">curl -X POST https://virtualsmsnumbers.com/api/v1/activations \
-H "Authorization: Bearer $VSN_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"service":"telegram","country":"PT"}'
# {"id":"1043872915","phone_number":"351926114508","status":"waiting",
# "price_cents":11,"expires_at":"2026-08-26T12:41:07Z"}
# 2. Long-poll until the code lands (blocks up to 120 s)
-kw">curl "https://virtualsmsnumbers.com/api/v1/activations/1043872915?wait=120" \
-H "Authorization: Bearer $VSN_KEY"
# {"id":"1043872915","status":"code_received",
# "messages":[{"code":"48219","text":"Telegram code: 48219"}]}
# 3. Release the number
-kw">curl -X POST https://virtualsmsnumbers.com/api/v1/activations/1043872915/complete \
-H "Authorization: Bearer $VSN_KEY"Ratenbegrenzungen
120 Anfragen pro Minute je Schlüssel, mit Spitzen von 20 pro Sekunde. Jede Antwort trägt X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset, und ein 429 sagt Ihnen, wie lange zu warten ist, statt Sie raten zu lassen.
Das Limit ist selten die Einschränkung, wenn die API wie vorgesehen genutzt wird: ein Long Poll statt neunzig Abfragen, ein Webhook statt eines Timers, und die Länder- und Dienstlisten beim Start zwischengespeichert. Wenn Sie wirklich mehr Spielraum brauchen, fragen Sie danach — ein Limit anzuheben ist für beide Seiten einfacher, als eine Flotte von Schlüsseln zu debuggen.
Idempotenz
Senden Sie einen Idempotency-Key-Header an POST /activations. Denselben Schlüssel innerhalb von 24 Stunden erneut zu senden, liefert die ursprüngliche Aktivierung in ihrem aktuellen Zustand samt Idempotent-Replay-Header zurück, statt eine zweite Nummer zu kaufen und Ihnen zweimal zu berechnen.
Der Schlüssel ist kein Hash des Körpers: Eine andere Nutzlast unter einem bereits benutzten Schlüssel liefert trotzdem die erste Aktivierung. Erzeugen Sie einen Schlüssel je logischem Kauf — eine UUID genügt — und verwenden Sie ihn über Wiederholungen hinweg, nie über Käufe hinweg.
Alte handler_api-Clients
Skripte, die für das klassische handler_api.php-Protokoll geschrieben wurden, laufen weiter. Richten Sie sie auf den Kompatibilitätsendpunkt, tauschen Sie den api_key, und dieselben Aktionen liefern dieselben ACCESS_- und STATUS_-Token wie eh und je.
Es ist eine Übersetzungsschicht über demselben Pool, Preise, Bestände und Erstattungen verhalten sich also identisch. Neuer Code sollte trotzdem /api/v1 nutzen: Die JSON-Antworten tragen Zeitstempel, Fehlercodes und Preisfelder, für die im Tokenformat kein Platz ist.
# Existing scripts keep working: same actions, same response tokens.
BASE="https://virtualsmsnumbers.com/stubs/handler_api.php"
-kw">curl "$BASE?api_key=$KEY&action=getNumber&service=tg&country=117"
# ACCESS_NUMBER:1043872915:351926114508
-kw">curl "$BASE?api_key=$KEY&action=getStatus&id=1043872915"
# STATUS_WAIT_CODE
# STATUS_OK:48219
-kw">curl "$BASE?api_key=$KEY&action=setStatus&id=1043872915&status=6"
# ACCESS_ACTIVATION
-kw">curl "$BASE?api_key=$KEY&action=getBalance"
# ACCESS_BALANCE:41.87Agenten, MCP und Discovery
Es gibt einen gehosteten MCP-Server, ein OpenAPI-3.1-Dokument und einen llms.txt-Index, ein Agent kann die drei benötigten Werkzeuge also ohne handgeschriebenen Klebecode finden. Richten Sie Ihren Client auf den Endpunkt unten, und er findet Kaufen, Warten und Freigeben.
Bevor Sie etwas Autonomes vom Guthaben ausgeben lassen: Beschränken Sie den Schlüssel auf numbers:read und numbers:write, setzen Sie bei jedem Kauf eine max_price_cents-Obergrenze, und geben Sie ihm einen eigenen Schlüssel, damit ein Widerruf nicht Ihre Produktivintegration mitnimmt.
{
"mcpServers": {
"virtualsmsnumbers": {
"type": "http",
"url": "https://virtualsmsnumbers.com/api/mcp",
"headers": { "Authorization": "Bearer vsn_live_xxxxxxxxxxxx" }
}
}
}Vor dem Produktivbetrieb
- Setzen Sie max_price_cents bei jedem Kauf. Preise bewegen sich mit dem Pool, und ein Agent ohne Obergrenze kauft bereitwillig das teure Ende.
- Behandeln Sie Bezeichner als undurchsichtige Zeichenketten. Aktivierungs-IDs haben heute zufällig zehn Ziffern; das ist keine Zusage, ihre Länge ebenso wenig.
- Verzweigen Sie über den Fehlercode, nie über die Meldung. Codes sind innerhalb einer Version stabil; Meldungen sind für Menschen geschrieben und werden umformuliert.
- Abonnieren Sie sms.received und prüfen Sie die Signatur — HMAC-SHA256 über den rohen Körper, mit fünf Minuten Replay-Fenster — statt einen Zustand abzufragen, über den Sie informiert werden können.
- Rechnen Sie mit den ganzzahligen Cent-Feldern. Die formatierten Zeichenketten daneben sind für die Anzeige und hängen von der Locale ab.
Die vollständige Referenz
Sechs Endpunkte, Fehlertabellen, Webhook-Nutzlasten, Scopes und die Zuordnung der alten Token.
Häufig gestellte Fragen
Die mittlere Zustellzeit liegt unter neun Sekunden ab dem Versand durch den Dienst. Den Long Poll gibt es, weil der Ausläufer lang ist: Die Aktivierung bleibt 20 Minuten offen und läuft dann in eine Erstattung, wenn nichts ankommt.
Nichts, was Sie behandeln müssten. Das Fenster schließt, das Guthaben wird automatisch zurückgebucht, und die Aktivierung endet in einem abgelaufenen Zustand, den Sie über die API lesen können.
Ja, und es kostet nichts. Schlüssel tragen feste Scopes, eine optionale IP-Allowlist und ein bei der Erstellung gewähltes Ablaufdatum, ein durchgesickerter Staging-Schlüssel kann also keine Nummern in der Produktion kaufen.
Es gibt schlanke, abhängigkeitsfreie Wrapper, aber die API besteht aus sechs Endpunkten über JSON — fetch, requests oder curl reichen für den Ablauf in drei Aufrufen wirklich aus.
Innerhalb einer Aktivierung ja: Weitere Nachrichten kommen auf derselben Nummer an, solange sie offen ist. Über Sitzungen hinweg brauchen Sie eine Miete, die die Leitung vier Stunden bis zwölf Monate hält.
Nein. Es ist derselbe Pool zu denselben Preisen; nur die Kodierung der Antworten unterscheidet sich.