Referenz

TG Validator API-Referenz

Alle Endpunkte teilen sich einen API-Schlüssel und ein Guthaben.

Eintrag	Wert
Basis-URL	https://tgvalidator.com
Auth-Header	X-API-Key: sk_your_api_key
Antwort-Envelope	{ code, msg, data }

Preise werden hier nicht aufgeführt; jedes Produkt wird pro erfolgreicher Prüfung berechnet. Preise ansehen

Authentifizierung

Verwenden Sie einen in den Einstellungen erstellten API-Schlüssel und senden Sie ihn bei jeder Anfrage mit.

Auth-Header

X-API-Key: sk_your_api_key

Halten Sie Ihren API-Schlüssel geheimRufen Sie diesen Endpunkt immer von Ihrem Server aus auf. Jeder, der den Schlüssel besitzt, kann Ihr Guthaben verbrauchen.

Synchrone Prüfungen

POST/api/v1/checkPOST/api/v1/batch-check

Übermitteln Sie eine Telefonnummer oder bis zu 100 in einer Anfrage und lesen Sie das Ergebnis in derselben Antwort. Kein Polling, keine Callbacks. Ein unbestimmtes Ergebnis liefert 422 mit dem Code 42200 und wird nicht berechnet. Eine Mehrfachanfrage behält die Eingabereihenfolge bei, rechnet jede Kennung einzeln ab und hat 300 Sekunden Zeit – wird sie nicht rechtzeitig fertig, schlägt die gesamte Anfrage fehl und alle Abbuchungen werden erstattet.

Parameter

Feld	Typ	Beschreibung
`service_type`	string	Produktcode, eines der unten aufgeführten Produkte.
`identifier`	string	Einzelprüfung: eine Telefonnummer. Der Server normalisiert sie.
`identifiers`	string[]	Mehrfachprüfung: 1 bis 100 Telefonnummern. Die Antwort behält diese Reihenfolge bei.

Produkte in dieser Gruppe

Telegram-RegistrierungsprüfungtgBestätigen Sie, ob eine Nummer bei Telegram registriert ist – hilfreich, um eine Kontaktliste vor dem Versand zu prüfen.Produktseite

Telegram-Registrierungsprüfung

tgTelefon

Bestätigen Sie, ob eine Nummer bei Telegram registriert ist – hilfreich, um eine Kontaktliste vor dem Versand zu prüfen.

Einzelprüfung

POST/api/v1/check

Anfrage

curl -X POST "https://tgvalidator.com/api/v1/check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "tg", "identifier": "+17253100591" }'

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "tg",
    "identifier": "+17253100591",
    "registered": true
  }
}

Antwortfelder

Feld	Typ	Beschreibung
`registered`	boolean	Ob die Nummer bei Telegram registriert ist.

Mehrfachprüfung

POST/api/v1/batch-check

Anfrage

curl -X POST "https://tgvalidator.com/api/v1/batch-check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "tg", "identifiers": ["+17253100591", "+14155550000", "12345"] }'

Antwort

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "tg",
    "total": 3,
    "succeeded": 2,
    "failed": 1,
    "results": [
      {
        "identifier": "+17253100591",
        "exists": true,
        "registered": true
      },
      {
        "identifier": "+14155550000",
        "exists": true,
        "registered": false
      },
      {
        "identifier": "12345",
        "exists": false
      }
    ]
  }
}

Antwortfelder

Feld	Typ	Beschreibung
`exists`	boolean	Ob diese Nummer ein Ergebnis geliefert hat. false bedeutet, dass das Format ungültig war, das Ergebnis unbestimmt war oder die Prüfung fehlgeschlagen ist; bei false ist keines der folgenden Felder vorhanden.
`registered`	boolean	Ob die Nummer registriert ist. Nur vorhanden, wenn exists true ist, mit derselben Bedeutung wie bei der Einzelprüfung.

Asynchrone Prüfungen

POST/api/v1/bulk-tasksGET/api/v1/bulk-tasks/{id}

Laden Sie eine Datei hoch und erhalten Sie sofort eine Aufgaben-ID; fragen Sie diese ID dann ab, bis sie erfolgreich ist. Die erfolgreiche Antwort enthält result_url, den Download-Link für das Ergebnis. Es gibt nur zwei Aktionen: übermitteln und abfragen. Fragen Sie höchstens einmal alle 30 Sekunden ab.

Parameter

Feld	Typ	Beschreibung
`service_type`	string	Produktcode für die Massenprüfung, eines der unten aufgeführten Produkte.
`country`	string	ISO-3166-1-Code wie `US`. Erforderlich für Nummernaufgaben: Jede Nummer muss ihre Ländervorwahl enthalten und zu diesem Land gehören (Nummern, die das nicht tun, werden ausgelassen und nicht berechnet); außerdem bestimmt er das Routing. Bei multipart muss er vor `file` stehen.
`file`	file	Eine `.txt`- oder `.csv`-Datei mit einer Kennung pro Zeile, bis zu `max_file_bytes` (standardmäßig 20MB).
`Idempotency-Key`	header	Optional, bis zu 128 Zeichen. Wird derselbe Schlüssel erneut gesendet, wird die ursprüngliche Aufgabe zurückgegeben, statt eine zweite zu erstellen.

Produkte in dieser Gruppe

Telegram-Massenprüfung der Registrierungtg_batchLaden Sie eine ganze Datei mit Nummern hoch, finden Sie heraus, welche bei Telegram registriert sind, und laden Sie die Ergebnisdatei herunter, sobald sie fertig ist.Produktseite
Telegram-Massenprüfung der Aktivitättg_active_batchRegistrierungsstatus plus Benutzer-ID, Benutzername und aktive Tage – Tage seit der letzten Anzeige als „zuletzt online“ – für eine ganze Liste.Produktseite
Telegram-Massenprüfung des Profilstg_profile_batchBenutzer-ID, Benutzername, aktive Tage, Profilbild-URL sowie aus dem Profilbild geschätztes Alter, Geschlecht und Hautton – für eine ganze Liste.Produktseite
Telegram-Massenprüfung von Benutzernamentg_username_batchLaden Sie eine Liste mit Telegram-Benutzernamen hoch und bestätigen Sie, welche zu echten Konten gehören.Produktseite
Telegram-Massenprüfung von Benutzernamen-Profilentg_username_profile_batchBenutzer-ID, aktive Tage und Profilbild-URL für eine ganze Liste von Benutzernamen.Produktseite

Telegram-Massenprüfung der Registrierung

tg_batchTelefon1.000–500.000 pro Aufgabe

Laden Sie eine ganze Datei mit Nummern hoch, finden Sie heraus, welche bei Telegram registriert sind, und laden Sie die Ergebnisdatei herunter, sobald sie fertig ist.

Aufgabe übermitteln

POST/api/v1/bulk-tasks

Anfrage

curl -X POST "https://tgvalidator.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=tg_batch \
  -F country=US \
  -F file=@numbers.txt

Antwort

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "tg_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1015,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Aufgabe abfragen

GET/api/v1/bulk-tasks/{id}

Anfrage

curl "https://tgvalidator.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Antwort

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "tg_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1000,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 12,
    "preparing": false,
    "success_cnt": 990,
    "failure_cnt": 10,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Ergebnisspalten

Feld	Beispiel:	Beschreibung
`identifier`	17253100591	Die übermittelte Nummer als reine Ziffern mit Ländervorwahl, ohne Pluszeichen oder Leerzeichen (z. B. 17253100591).
`activated`	true	Ob die Nummer bei Telegram registriert ist: true oder false.

Telegram-Massenprüfung der Aktivität

tg_active_batchTelefon1.000–500.000 pro Aufgabe

Registrierungsstatus plus Benutzer-ID, Benutzername und aktive Tage – Tage seit der letzten Anzeige als „zuletzt online“ – für eine ganze Liste.

Aufgabe übermitteln

POST/api/v1/bulk-tasks

Anfrage

curl -X POST "https://tgvalidator.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=tg_active_batch \
  -F country=US \
  -F file=@numbers.txt

Antwort

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "tg_active_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1015,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Aufgabe abfragen

GET/api/v1/bulk-tasks/{id}

Anfrage

curl "https://tgvalidator.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Antwort

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "tg_active_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1000,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 12,
    "preparing": false,
    "success_cnt": 990,
    "failure_cnt": 10,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Ergebnisspalten

Feld	Beispiel:	Beschreibung
`identifier`	17253100591	Die übermittelte Nummer als reine Ziffern mit Ländervorwahl, ohne Pluszeichen oder Leerzeichen (z. B. 17253100591).
`activated`	true	Ob die Nummer bei Telegram registriert ist: true oder false. Ist der Wert nicht true, bleiben alle anderen Spalten dieser Zeile leer.
`uid`	1234567890	Telegram-Benutzer-ID.
`username`	alex_kim	Benutzername; leer, wenn das Konto keinen hat.
`activedays`	9	Tage seit der letzten Anzeige des Kontos als „zuletzt online“, als ganze Zahl – je kleiner, desto aktueller. Verbirgt das Konto seinen genauen Zeitpunkt, gibt Telegram nur einen Bereich preis, und der Wert ist eine Annäherung: 0 (kürzlich), 7 (innerhalb einer Woche), 30 (innerhalb eines Monats) oder 1000 (vor langer Zeit).

Telegram-Massenprüfung des Profils

tg_profile_batchTelefon1.000–500.000 pro Aufgabe

Benutzer-ID, Benutzername, aktive Tage, Profilbild-URL sowie aus dem Profilbild geschätztes Alter, Geschlecht und Hautton – für eine ganze Liste.

Aufgabe übermitteln

POST/api/v1/bulk-tasks

Anfrage

curl -X POST "https://tgvalidator.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=tg_profile_batch \
  -F country=US \
  -F file=@numbers.txt

Antwort

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "tg_profile_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1015,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Aufgabe abfragen

GET/api/v1/bulk-tasks/{id}

Anfrage

curl "https://tgvalidator.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Antwort

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "tg_profile_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1000,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 12,
    "preparing": false,
    "success_cnt": 990,
    "failure_cnt": 10,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Ergebnisspalten

Feld	Beispiel:	Beschreibung
`identifier`	17253100591	Die übermittelte Nummer als reine Ziffern mit Ländervorwahl, ohne Pluszeichen oder Leerzeichen (z. B. 17253100591).
`activated`	true	Ob die Nummer bei Telegram registriert ist: true oder false. Ist der Wert nicht true, bleiben alle anderen Spalten dieser Zeile leer.
`uid`	1234567890	Telegram-Benutzer-ID.
`username`	alex_kim	Benutzername; leer, wenn das Konto keinen hat.
`activedays`	9	Tage seit der letzten Anzeige des Kontos als „zuletzt online“, als ganze Zahl – je kleiner, desto aktueller. Verbirgt das Konto seinen genauen Zeitpunkt, gibt Telegram nur einen Bereich preis, und der Wert ist eine Annäherung: 0 (kürzlich), 7 (innerhalb einer Woche), 30 (innerhalb eines Monats) oder 1000 (vor langer Zeit).
`avatar_url`	https://telegram.waavatar.xyz/v/example.jpg	Profilbild-URL; leer, wenn das Konto kein Profilbild hat.
`age`	31	Aus dem Profilbild geschätztes Alter; leer, wenn es nicht geschätzt werden kann.
`gender`	male	Aus dem Profilbild geschätztes Geschlecht: male oder female; unknown, wenn es nicht erkannt werden kann, leer, wenn kein Profilbild vorhanden ist.
`skin_color`	white	Aus dem Profilbild geschätzter Hautton, z. B. white, middle_eastern, east_asian; unknown, wenn er nicht erkannt werden kann, leer, wenn kein Profilbild vorhanden ist.

Telegram-Massenprüfung von Benutzernamen

tg_username_batchBenutzername1.000–500.000 pro Aufgabe

Laden Sie eine Liste mit Telegram-Benutzernamen hoch und bestätigen Sie, welche zu echten Konten gehören.

Aufgabe übermitteln

POST/api/v1/bulk-tasks

Anfrage

curl -X POST "https://tgvalidator.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=tg_username_batch \
  -F file=@usernames.txt

Antwort

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "tg_username_batch",
    "status": "processing",
    "submitted_lines": 1015,
    "total": 1015,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Aufgabe abfragen

GET/api/v1/bulk-tasks/{id}

Anfrage

curl "https://tgvalidator.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Antwort

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "tg_username_batch",
    "status": "success",
    "submitted_lines": 1015,
    "total": 1000,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 12,
    "preparing": false,
    "success_cnt": 990,
    "failure_cnt": 10,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Ergebnisspalten

Feld	Beispiel:	Beschreibung
`identifier`	alex_kim	Der übermittelte Benutzername ohne @ oder t.me/ (z. B. alex_kim).
`activated`	true	Ob der Benutzername zu einem bestehenden Telegram-Konto gehört: true oder false.

Telegram-Massenprüfung von Benutzernamen-Profilen

tg_username_profile_batchBenutzername1.000–500.000 pro Aufgabe

Benutzer-ID, aktive Tage und Profilbild-URL für eine ganze Liste von Benutzernamen.

Aufgabe übermitteln

POST/api/v1/bulk-tasks

Anfrage

curl -X POST "https://tgvalidator.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=tg_username_profile_batch \
  -F file=@usernames.txt

Antwort

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "tg_username_profile_batch",
    "status": "processing",
    "submitted_lines": 1015,
    "total": 1015,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Aufgabe abfragen

GET/api/v1/bulk-tasks/{id}

Anfrage

curl "https://tgvalidator.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Antwort

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "tg_username_profile_batch",
    "status": "success",
    "submitted_lines": 1015,
    "total": 1000,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 12,
    "preparing": false,
    "success_cnt": 990,
    "failure_cnt": 10,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Ergebnisspalten

Feld	Beispiel:	Beschreibung
`identifier`	alex_kim	Der übermittelte Benutzername ohne @ oder t.me/ (z. B. alex_kim).
`activated`	true	Ob der Benutzername zu einem bestehenden Telegram-Konto gehört: true oder false. Ist der Wert nicht true, bleiben alle anderen Spalten dieser Zeile leer.
`uid`	1234567890	Telegram-Benutzer-ID; kann auch bei einem bestehenden Konto leer sein.
`activedays`	9	Tage seit der letzten Anzeige des Kontos als „zuletzt online“, als ganze Zahl – je kleiner, desto aktueller. Verbirgt das Konto seinen genauen Zeitpunkt, gibt Telegram nur einen Bereich preis, und der Wert ist eine Annäherung: 0 (kürzlich), 7 (innerhalb einer Woche), 30 (innerhalb eines Monats) oder 1000 (vor langer Zeit). Kann leer sein, wenn das Konto keine Informationen zu „zuletzt online“ preisgibt.
`avatar_url`	https://cdn5.telesco.pe/file/example.jpg	Profilbild-URL; leer, wenn das Konto kein Profilbild hat.

Guthaben

GET/api/v1/balance

Liest das aktuelle Kontoguthaben in USD-Mikroeinheiten aus. Nur lesend: Es wird kein Prüfdatensatz erstellt und nichts berechnet.

Guthaben

GET/api/v1/balance

Anfrage

curl "https://tgvalidator.com/api/v1/balance" \
  -H "X-API-Key: sk_your_api_key"

Antwort

{
  "code": 0,
  "msg": "ok",
  "data": {
    "balance_micros": 12500000
  }
}

Parallelität, Zeitlimits und Wiederholungsverhalten

Telegram-Registrierungsprüfungen erfolgen synchron. Entscheiden Sie anhand des zurückgegebenen Codes, ob Sie das Ergebnis übernehmen oder die Anfrage wiederholen.

Feld	Beschreibung
`5 gleichzeitige Anfragen pro Benutzer`	Einzel- und Mehrfachprüfungen teilen sich dieses Limit, und eine Mehrfachanfrage zählt als eine Anfrage, unabhängig davon, wie viele Nummern sie enthält. Zusätzlich läuft pro Konto jeweils nur eine Mehrfachprüfung; eine zweite wird abgelehnt, bis die erste abgeschlossen ist. Wird eines der Limits erreicht, wird sofort code 42901 ohne Berechnung zurückgegeben, zusammen mit einem Retry-After-Header – senden Sie die Anfrage erneut, sobald eine laufende Anfrage abgeschlossen ist.
`60 s Einzelprüfung, 300 s Mehrfachprüfung`	Bei Überschreitung des Zeitlimits wird code 50400 ohne Berechnung zurückgegeben. Eine Mehrfachprüfung mit Zeitüberschreitung schlägt als Ganzes fehl – keine Teilergebnisse, und der volle Betrag wird erstattet.
`Eine Mehrfachprüfung umfasst bis zu 100 Nummern`	Die Ergebnisse behalten Reihenfolge und Länge der Übermittlung bei. Pro Konto läuft jeweils eine Mehrfachprüfung; senden Sie den nächsten Stapel, sobald der vorherige zurückgekommen ist.

Fehlercodes

Code	Beschreibung
`40000`	Nicht unterstützter Diensttyp oder widersprüchliche Anfragefelder
`40001`	Ungültiger JSON-Body
`40002`	Ungültige Nummer
`40100`	Fehlender oder ungültiger API-Schlüssel
`40200`	Unzureichendes Guthaben
`42200`	Die Nummer konnte derzeit nicht bestimmt werden. Es werden keine Daten zurückgegeben, und die Anfrage wird nicht berechnet
`42900`	Ein Nutzungskontingent ist aufgebraucht, oder es gibt zu viele nicht abgeschlossene Bestellungen
`42901`	Alle fünf Plätze für gleichzeitige Anfragen sind belegt, oder auf diesem Konto läuft bereits eine Mehrfachprüfung; senden Sie erneut, sobald eine laufende Anfrage abgeschlossen ist. Die abgelehnte Anfrage wird nicht berechnet und enthält einen Retry-After-Header
`50303`	Der Dienst ist derzeit ausgelastet; nicht berechnet. Warten Sie die in Retry-After angegebenen Sekunden ab und senden Sie dieselbe Anfrage erneut
`50400`	Die Prüfung wurde nicht innerhalb ihres Zeitlimits abgeschlossen und wird nicht berechnet; wiederholen Sie sie. Eine Zeitüberschreitung beim Stapel lässt den gesamten Stapel fehlschlagen und erstattet den vollen Betrag
`50300`	Wartung des Prüfdienstes