Referência

TG Validator Referência da API

Todos os endpoints compartilham uma chave de API e um saldo.

Item	Valor
URL base	https://tgvalidator.com
Cabeçalho de autenticação	X-API-Key: sk_your_api_key
Envelope da resposta	{ code, msg, data }

Os preços não são listados aqui; todos os produtos são cobrados por verificação bem-sucedida. Ver preços

Autenticação

Use uma chave de API criada em Configurações e envie-a em todas as solicitações.

Cabeçalho de autenticação

X-API-Key: sk_your_api_key

Mantenha sua chave de API em segredoSempre chame este endpoint a partir do seu servidor. Qualquer pessoa que tenha a chave pode gastar seu saldo.

Verificações síncronas

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

Envie um número de telefone, ou até 100 em uma única solicitação, e leia o resultado na mesma resposta. Sem polling, sem callbacks. Um resultado indeterminado retorna 422 com o código 42200 e não é cobrado. Uma solicitação múltipla mantém a ordem de entrada, cobra cada identificador de forma independente e tem 300 segundos para terminar — caso contrário, a solicitação inteira falha e todas as cobranças são reembolsadas.

Parâmetros

Campo	Tipo	Descrição
`service_type`	string	Código do produto, um dos produtos listados abaixo.
`identifier`	string	Verificação única: um número de telefone. O servidor o normaliza.
`identifiers`	string[]	Verificação múltipla: de 1 a 100 números de telefone. A resposta preserva esta ordem.

Produtos deste grupo

Verificação de registro no TelegramtgConfirme se um número está registrado no Telegram — útil para verificar uma lista de contatos antes de enviar.Página do produto

Verificação de registro no Telegram

tgtelefone

Confirme se um número está registrado no Telegram — útil para verificar uma lista de contatos antes de enviar.

Verificação única

POST/api/v1/check

Solicitação

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 da resposta

Campo	Tipo	Descrição
`registered`	boolean	Se o número está registrado no Telegram.

Verificação múltipla

POST/api/v1/batch-check

Solicitação

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

Resposta

{
  "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 da resposta

Campo	Tipo	Descrição
`exists`	boolean	Se este número gerou um resultado. false significa que o formato era inválido, o resultado foi indeterminado ou a verificação falhou; quando false, nenhum dos campos abaixo está presente.
`registered`	boolean	Se o número está registrado. Presente apenas quando exists é true, com o mesmo significado da verificação única.

Verificações assíncronas

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

Envie um arquivo e receba um ID de tarefa imediatamente; depois, consulte esse ID até que seja concluído com sucesso. A resposta de sucesso inclui result_url, o link para baixar o resultado. Existem apenas duas ações: enviar e consultar. Não consulte com frequência maior que uma vez a cada 30 segundos.

Parâmetros

Campo	Tipo	Descrição
`service_type`	string	Código do produto em massa, um dos produtos listados abaixo.
`country`	string	Código ISO 3166-1, como `US`. Obrigatório para tarefas de números: cada número deve incluir o código do país e pertencer a este país (os números que não atendem a isso são excluídos e não são cobrados); também define o roteamento. Em multipart, deve vir antes de `file`.
`file`	file	Um `.txt` ou `.csv` com um identificador por linha, até `max_file_bytes` (20MB por padrão).
`Idempotency-Key`	header	Opcional, até 128 caracteres. Reenviar a mesma chave retorna a tarefa original em vez de criar uma segunda.

Produtos deste grupo

Verificação de registro em massa do Telegramtg_batchEnvie um arquivo inteiro de números, descubra quais estão registrados no Telegram e baixe o arquivo de resultado quando terminar.Página do produto
Verificação de atividade em massa do Telegramtg_active_batchStatus de registro mais ID de usuário, nome de usuário e dias de atividade — dias desde que cada conta foi vista por último — em uma lista inteira.Página do produto
Verificação de perfil em massa do Telegramtg_profile_batchID de usuário, nome de usuário, dias de atividade, URL da foto de perfil e idade, gênero e tom de pele estimados a partir da foto — em uma lista inteira.Página do produto
Verificação de nomes de usuário em massa do Telegramtg_username_batchEnvie uma lista de nomes de usuário do Telegram e confirme quais pertencem a contas reais.Página do produto
Verificação de perfil por nome de usuário em massa do Telegramtg_username_profile_batchID de usuário, dias de atividade e URL da foto de perfil para uma lista inteira de nomes de usuário.Página do produto

Verificação de registro em massa do Telegram

tg_batchtelefone1.000–500.000 por tarefa

Envie um arquivo inteiro de números, descubra quais estão registrados no Telegram e baixe o arquivo de resultado quando terminar.

Enviar uma tarefa

POST/api/v1/bulk-tasks

Solicitação

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

Resposta

{
  "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 a tarefa

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

Solicitação

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

Resposta

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

Colunas do resultado

Campo	exemplo:	Descrição
`identifier`	17253100591	O número enviado apenas em dígitos, com o código do país, sem sinal de mais nem espaços (ex.: 17253100591).
`activated`	true	Se o número está registrado no Telegram: true ou false.

Verificação de atividade em massa do Telegram

tg_active_batchtelefone1.000–500.000 por tarefa

Status de registro mais ID de usuário, nome de usuário e dias de atividade — dias desde que cada conta foi vista por último — em uma lista inteira.

Enviar uma tarefa

POST/api/v1/bulk-tasks

Solicitação

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

Resposta

{
  "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 a tarefa

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

Solicitação

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

Resposta

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

Colunas do resultado

Campo	exemplo:	Descrição
`identifier`	17253100591	O número enviado apenas em dígitos, com o código do país, sem sinal de mais nem espaços (ex.: 17253100591).
`activated`	true	Se o número está registrado no Telegram: true ou false. Quando não é true, todas as outras colunas dessa linha ficam vazias.
`uid`	1234567890	ID de usuário do Telegram.
`username`	alex_kim	Nome de usuário; vazio quando a conta não tem um.
`activedays`	9	Dias desde que a conta foi vista por último, como número inteiro — quanto menor, mais recente. Quando a conta oculta o horário exato do visto por último, o Telegram revela apenas um intervalo e o valor é uma aproximação: 0 (recentemente), 7 (na última semana), 30 (no último mês) ou 1000 (há muito tempo).

Verificação de perfil em massa do Telegram

tg_profile_batchtelefone1.000–500.000 por tarefa

ID de usuário, nome de usuário, dias de atividade, URL da foto de perfil e idade, gênero e tom de pele estimados a partir da foto — em uma lista inteira.

Enviar uma tarefa

POST/api/v1/bulk-tasks

Solicitação

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

Resposta

{
  "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 a tarefa

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

Solicitação

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

Resposta

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

Colunas do resultado

Campo	exemplo:	Descrição
`identifier`	17253100591	O número enviado apenas em dígitos, com o código do país, sem sinal de mais nem espaços (ex.: 17253100591).
`activated`	true	Se o número está registrado no Telegram: true ou false. Quando não é true, todas as outras colunas dessa linha ficam vazias.
`uid`	1234567890	ID de usuário do Telegram.
`username`	alex_kim	Nome de usuário; vazio quando a conta não tem um.
`activedays`	9	Dias desde que a conta foi vista por último, como número inteiro — quanto menor, mais recente. Quando a conta oculta o horário exato do visto por último, o Telegram revela apenas um intervalo e o valor é uma aproximação: 0 (recentemente), 7 (na última semana), 30 (no último mês) ou 1000 (há muito tempo).
`avatar_url`	https://telegram.waavatar.xyz/v/example.jpg	URL da foto de perfil; vazia quando a conta não tem foto.
`age`	31	Idade estimada a partir da foto de perfil; vazia quando não é possível estimar.
`gender`	male	Gênero estimado a partir da foto de perfil: male ou female; unknown quando não é possível reconhecer, vazio quando não há foto.
`skin_color`	white	Tom de pele estimado a partir da foto de perfil, ex.: white, middle_eastern, east_asian; unknown quando não é possível reconhecer, vazio quando não há foto.

Verificação de nomes de usuário em massa do Telegram

tg_username_batchnome de usuário1.000–500.000 por tarefa

Envie uma lista de nomes de usuário do Telegram e confirme quais pertencem a contas reais.

Enviar uma tarefa

POST/api/v1/bulk-tasks

Solicitação

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

Resposta

{
  "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 a tarefa

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

Solicitação

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

Resposta

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

Colunas do resultado

Campo	exemplo:	Descrição
`identifier`	alex_kim	O nome de usuário enviado, sem @ ou t.me/ (ex.: alex_kim).
`activated`	true	Se o nome de usuário pertence a uma conta existente do Telegram: true ou false.

Verificação de perfil por nome de usuário em massa do Telegram

tg_username_profile_batchnome de usuário1.000–500.000 por tarefa

ID de usuário, dias de atividade e URL da foto de perfil para uma lista inteira de nomes de usuário.

Enviar uma tarefa

POST/api/v1/bulk-tasks

Solicitação

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

Resposta

{
  "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 a tarefa

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

Solicitação

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

Resposta

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

Colunas do resultado

Campo	exemplo:	Descrição
`identifier`	alex_kim	O nome de usuário enviado, sem @ ou t.me/ (ex.: alex_kim).
`activated`	true	Se o nome de usuário pertence a uma conta existente do Telegram: true ou false. Quando não é true, todas as outras colunas dessa linha ficam vazias.
`uid`	1234567890	ID de usuário do Telegram; pode ficar vazio mesmo para uma conta existente.
`activedays`	9	Dias desde que a conta foi vista por último, como número inteiro — quanto menor, mais recente. Quando a conta oculta o horário exato do visto por último, o Telegram revela apenas um intervalo e o valor é uma aproximação: 0 (recentemente), 7 (na última semana), 30 (no último mês) ou 1000 (há muito tempo). Pode ficar vazio quando a conta não revela nenhuma informação de visto por último.
`avatar_url`	https://cdn5.telesco.pe/file/example.jpg	URL da foto de perfil; vazia quando a conta não tem foto.

Saldo

GET/api/v1/balance

Lê o saldo atual da conta em micros de USD. Somente leitura: não cria registro de verificação nem cobra nada.

Saldo

GET/api/v1/balance

Solicitação

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

Resposta

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

Concorrência, tempos limite e comportamento de novas tentativas

As verificações de registro no Telegram são síncronas. Use o code retornado para decidir se aceita o resultado ou tenta novamente.

Campo	Descrição
`5 solicitações simultâneas por usuário`	As verificações únicas e múltiplas compartilham este limite, e uma solicitação múltipla conta como uma única solicitação, independentemente de quantos números contenha. Além disso, apenas uma verificação múltipla por conta é executada por vez; uma segunda é rejeitada até a primeira terminar. Atingir qualquer um dos limites retorna imediatamente o código 42901, sem cobrança, com um cabeçalho Retry-After — reenvie assim que uma solicitação em andamento terminar.
`60s para única, 300s para múltipla`	Exceder o limite de tempo retorna o código 50400, sem cobrança. Uma verificação múltipla que excede o tempo falha por inteiro — sem resultados parciais, e o valor total é reembolsado.
`Uma verificação múltipla aceita até 100 números`	Os resultados preservam a ordem e a quantidade do envio. Uma verificação múltipla por conta é executada por vez; envie o próximo lote depois que o anterior retornar.

Códigos de erro

Código	Descrição
`40000`	Tipo de serviço não suportado ou campos da solicitação conflitantes
`40001`	Corpo JSON inválido
`40002`	Número inválido
`40100`	Chave de API ausente ou inválida
`40200`	Saldo insuficiente
`42200`	Não foi possível determinar o número neste momento. Nenhum dado é retornado e a solicitação não é cobrada
`42900`	Uma cota de uso foi esgotada ou há pedidos não concluídos demais
`42901`	As cinco vagas de solicitações simultâneas estão ocupadas, ou já há uma verificação múltipla em execução nesta conta; envie depois que uma solicitação em andamento terminar. A solicitação rejeitada não é cobrada e traz um cabeçalho Retry-After
`50303`	O serviço está no limite da capacidade agora; sem cobrança. Aguarde os segundos indicados em Retry-After e reenvie a mesma solicitação
`50400`	A verificação não terminou dentro do tempo limite e não é cobrada; tente novamente. O tempo esgotado de um lote faz o lote inteiro falhar e reembolsa o valor total
`50300`	Manutenção do serviço de validação