Referencia

TG Validator Referencia de la API

Todos los endpoints comparten una clave API y un saldo.

Elemento	Valor
URL base	https://tgvalidator.com
Cabecera de autenticación	X-API-Key: sk_your_api_key
Estructura de la respuesta	{ code, msg, data }

Los precios no se indican aquí; cada producto se factura por verificación correcta. Ver precios

Autenticación

Use una clave API creada en Configuración y envíela con cada solicitud.

Cabecera de autenticación

X-API-Key: sk_your_api_key

Mantenga su clave API en secretoLlame siempre a este endpoint desde su servidor. Cualquiera que tenga la clave puede gastar su saldo.

Verificaciones síncronas

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

Envíe un número de teléfono, o hasta 100 en una sola solicitud, y lea el resultado en la misma respuesta. Sin sondeo ni callbacks. Un resultado indeterminado devuelve 422 con el código 42200 y no se cobra. Una solicitud múltiple conserva el orden de entrada, factura cada identificador de forma independiente y dispone de 300 segundos para finalizar; si no lo consigue, toda la solicitud falla y se reembolsan todos los cargos.

Parámetros

Campo	Tipo	Descripción
`service_type`	string	Código de producto, uno de los productos indicados a continuación.
`identifier`	string	Verificación individual: un número de teléfono. El servidor lo normaliza.
`identifiers`	string[]	Verificación múltiple: de 1 a 100 números de teléfono. La respuesta conserva este orden.

Productos de este grupo

Verificación de registro en TelegramtgConfirme si un número está registrado en Telegram: útil para revisar una lista de contactos antes de enviar mensajes.Página del producto

Verificación de registro en Telegram

tgteléfono

Confirme si un número está registrado en Telegram: útil para revisar una lista de contactos antes de enviar mensajes.

Verificación individual

POST/api/v1/check

Solicitud

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
  }
}

Campos de la respuesta

Campo	Tipo	Descripción
`registered`	boolean	Si el número está registrado en Telegram.

Verificación múltiple

POST/api/v1/batch-check

Solicitud

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"] }'

Respuesta

{
  "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
      }
    ]
  }
}

Campos de la respuesta

Campo	Tipo	Descripción
`exists`	boolean	Si este número produjo un resultado. false significa que el formato no era válido, que el resultado fue indeterminado o que la verificación falló; cuando es false, no aparece ninguno de los campos siguientes.
`registered`	boolean	Si el número está registrado. Solo aparece cuando exists es true, con el mismo significado que en la verificación individual.

Verificaciones asíncronas

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

Suba un archivo y obtenga al instante un ID de tarea; después, consulte ese ID hasta que se complete correctamente. La respuesta correcta incluye result_url, el enlace de descarga del resultado. Solo existen dos acciones: enviar y consultar. No sondee más de una vez cada 30 segundos.

Parámetros

Campo	Tipo	Descripción
`service_type`	string	Código de producto masivo, uno de los productos indicados a continuación.
`country`	string	Código ISO 3166-1, como `US`. Obligatorio para las tareas de números: cada número debe incluir su código de país y pertenecer a este país (los que no lo cumplan se excluyen y no se cobran); también selecciona el enrutamiento. En multipart debe ir antes de `file`.
`file`	file	Un archivo `.txt` o `.csv` con un identificador por línea, de hasta `max_file_bytes` (20MB por defecto).
`Idempotency-Key`	header	Opcional, hasta 128 caracteres. Repetir la misma clave devuelve la tarea original en lugar de crear una segunda.

Productos de este grupo

Verificación masiva de registro en Telegramtg_batchSuba un archivo completo de números, averigüe cuáles están registrados en Telegram y descargue el archivo de resultados cuando termine.Página del producto
Verificación masiva de actividad en Telegramtg_active_batchEstado de registro más ID de usuario, nombre de usuario y días de actividad (días desde la última conexión de cada cuenta) en toda una lista.Página del producto
Verificación masiva de perfil de Telegramtg_profile_batchID de usuario, nombre de usuario, días de actividad, URL del avatar y edad, género y tono de piel estimados a partir del avatar, en toda una lista.Página del producto
Verificación masiva de nombres de usuario de Telegramtg_username_batchSuba una lista de nombres de usuario de Telegram y confirme cuáles pertenecen a cuentas reales.Página del producto
Verificación masiva de perfil por nombre de usuario de Telegramtg_username_profile_batchID de usuario, días de actividad y URL del avatar para toda una lista de nombres de usuario.Página del producto

Verificación masiva de registro en Telegram

tg_batchteléfono1000–500.000 por tarea

Suba un archivo completo de números, averigüe cuáles están registrados en Telegram y descargue el archivo de resultados cuando termine.

Enviar una tarea

POST/api/v1/bulk-tasks

Solicitud

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

Respuesta

{
  "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"
  }
}

Consultar la tarea

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

Solicitud

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

Respuesta

{
  "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"
  }
}

Columnas del resultado

Campo	ejemplo:	Descripción
`identifier`	17253100591	El número enviado como dígitos sin formato con el código de país, sin signo más ni espacios (p. ej., 17253100591).
`activated`	true	Si el número está registrado en Telegram: true o false.

Verificación masiva de actividad en Telegram

tg_active_batchteléfono1000–500.000 por tarea

Estado de registro más ID de usuario, nombre de usuario y días de actividad (días desde la última conexión de cada cuenta) en toda una lista.

Enviar una tarea

POST/api/v1/bulk-tasks

Solicitud

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

Respuesta

{
  "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"
  }
}

Consultar la tarea

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

Solicitud

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

Respuesta

{
  "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"
  }
}

Columnas del resultado

Campo	ejemplo:	Descripción
`identifier`	17253100591	El número enviado como dígitos sin formato con el código de país, sin signo más ni espacios (p. ej., 17253100591).
`activated`	true	Si el número está registrado en Telegram: true o false. Cuando no es true, todas las demás columnas de esa fila se dejan vacías.
`uid`	1234567890	ID de usuario de Telegram.
`username`	alex_kim	Nombre de usuario; vacío cuando la cuenta no tiene ninguno.
`activedays`	9	Días desde la última conexión de la cuenta, como número entero: cuanto menor, más reciente. Cuando la cuenta oculta su hora exacta de última conexión, Telegram solo revela un intervalo y el valor es una aproximación: 0 (recientemente), 7 (en la última semana), 30 (en el último mes) o 1000 (hace mucho tiempo).

Verificación masiva de perfil de Telegram

tg_profile_batchteléfono1000–500.000 por tarea

ID de usuario, nombre de usuario, días de actividad, URL del avatar y edad, género y tono de piel estimados a partir del avatar, en toda una lista.

Enviar una tarea

POST/api/v1/bulk-tasks

Solicitud

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

Respuesta

{
  "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"
  }
}

Consultar la tarea

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

Solicitud

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

Respuesta

{
  "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"
  }
}

Columnas del resultado

Campo	ejemplo:	Descripción
`identifier`	17253100591	El número enviado como dígitos sin formato con el código de país, sin signo más ni espacios (p. ej., 17253100591).
`activated`	true	Si el número está registrado en Telegram: true o false. Cuando no es true, todas las demás columnas de esa fila se dejan vacías.
`uid`	1234567890	ID de usuario de Telegram.
`username`	alex_kim	Nombre de usuario; vacío cuando la cuenta no tiene ninguno.
`activedays`	9	Días desde la última conexión de la cuenta, como número entero: cuanto menor, más reciente. Cuando la cuenta oculta su hora exacta de última conexión, Telegram solo revela un intervalo y el valor es una aproximación: 0 (recientemente), 7 (en la última semana), 30 (en el último mes) o 1000 (hace mucho tiempo).
`avatar_url`	https://telegram.waavatar.xyz/v/example.jpg	URL del avatar; vacía cuando la cuenta no tiene avatar.
`age`	31	Edad estimada a partir del avatar; vacía cuando no se puede estimar.
`gender`	male	Género estimado a partir del avatar: male o female; unknown cuando no se puede reconocer, vacío cuando no hay avatar.
`skin_color`	white	Tono de piel estimado a partir del avatar, p. ej. white, middle_eastern, east_asian; unknown cuando no se puede reconocer, vacío cuando no hay avatar.

Verificación masiva de nombres de usuario de Telegram

tg_username_batchnombre de usuario1000–500.000 por tarea

Suba una lista de nombres de usuario de Telegram y confirme cuáles pertenecen a cuentas reales.

Enviar una tarea

POST/api/v1/bulk-tasks

Solicitud

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

Respuesta

{
  "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"
  }
}

Consultar la tarea

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

Solicitud

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

Respuesta

{
  "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"
  }
}

Columnas del resultado

Campo	ejemplo:	Descripción
`identifier`	alex_kim	El nombre de usuario enviado, sin @ ni t.me/ (p. ej. alex_kim).
`activated`	true	Si el nombre de usuario pertenece a una cuenta de Telegram existente: true o false.

Verificación masiva de perfil por nombre de usuario de Telegram

tg_username_profile_batchnombre de usuario1000–500.000 por tarea

ID de usuario, días de actividad y URL del avatar para toda una lista de nombres de usuario.

Enviar una tarea

POST/api/v1/bulk-tasks

Solicitud

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

Respuesta

{
  "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"
  }
}

Consultar la tarea

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

Solicitud

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

Respuesta

{
  "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"
  }
}

Columnas del resultado

Campo	ejemplo:	Descripción
`identifier`	alex_kim	El nombre de usuario enviado, sin @ ni t.me/ (p. ej. alex_kim).
`activated`	true	Si el nombre de usuario pertenece a una cuenta de Telegram existente: true o false. Cuando no es true, todas las demás columnas de esa fila se dejan vacías.
`uid`	1234567890	ID de usuario de Telegram; puede estar vacío incluso en una cuenta existente.
`activedays`	9	Días desde la última conexión de la cuenta, como número entero: cuanto menor, más reciente. Cuando la cuenta oculta su hora exacta de última conexión, Telegram solo revela un intervalo y el valor es una aproximación: 0 (recientemente), 7 (en la última semana), 30 (en el último mes) o 1000 (hace mucho tiempo). Puede estar vacío cuando la cuenta no revela ninguna información de última conexión.
`avatar_url`	https://cdn5.telesco.pe/file/example.jpg	URL del avatar; vacía cuando la cuenta no tiene avatar.

Saldo

GET/api/v1/balance

Consulte el saldo actual de la cuenta en micros de USD. Solo lectura: no crea ningún registro de verificación ni cobra nada.

Saldo

GET/api/v1/balance

Solicitud

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

Respuesta

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

Concurrencia, tiempos de espera y comportamiento de reintento

Las verificaciones de registro en Telegram son síncronas. Use el código devuelto para decidir si acepta el resultado o reintenta.

Campo	Descripción
`5 solicitudes simultáneas por usuario`	Las verificaciones individuales y múltiples comparten este límite, y una solicitud múltiple cuenta como una sola solicitud, independientemente de cuántos números incluya. Además, solo se ejecuta una verificación múltiple por cuenta a la vez; una segunda se rechaza hasta que termine la primera. Alcanzar cualquiera de los dos límites devuelve de inmediato el código 42901 sin cargo, junto con una cabecera Retry-After: vuelva a enviar la solicitud cuando termine una solicitud en curso.
`60 s individual, 300 s múltiple`	Superar el tiempo límite devuelve el código 50400 sin cargo. Una verificación múltiple que supera el tiempo de espera falla en su totalidad: no hay resultados parciales y se reembolsa el importe completo.
`Una verificación múltiple admite hasta 100 números`	Los resultados conservan el orden y la longitud del envío. Solo se ejecuta una verificación múltiple por cuenta a la vez; envíe el siguiente lote cuando el anterior haya devuelto sus resultados.

Códigos de error

Código	Descripción
`40000`	Tipo de servicio no compatible o campos de la solicitud en conflicto
`40001`	Cuerpo JSON no válido
`40002`	Número no válido
`40100`	Clave API ausente o no válida
`40200`	Saldo insuficiente
`42200`	No se ha podido determinar el número en este momento. No se devuelven datos y la solicitud no se cobra
`42900`	Se ha agotado una cuota de uso o hay demasiados pedidos sin finalizar
`42901`	Las cinco plazas de solicitudes simultáneas están ocupadas o ya hay una verificación múltiple en ejecución en esta cuenta; envíe la solicitud cuando termine una solicitud en curso. La solicitud rechazada no se cobra e incluye una cabecera Retry-After
`50303`	El servicio está a plena capacidad en este momento; no se cobra. Espere los segundos indicados en Retry-After y vuelva a enviar la misma solicitud
`50400`	La verificación no finalizó dentro de su tiempo de espera y no se cobra; reinténtela. Si se agota el tiempo de un lote, falla el lote completo y se reembolsa el importe total
`50300`	Mantenimiento del servicio de validación