Fazer pedidos

1. Escolha um verificadorCopy Anchor Link

GET /checkers lista o que sua conta pode pedir, pelos seus preços. Cada um tem um id, como whatsapp_status_detection, e aceita telefones, e-mails ou nomes de usuário. Veja Verificadores.

curl "https://api.talismanleads.io/v1/checkers" \
  -H "Authorization: Bearer tl_live_your_key_here"

2. Envie sua listaCopy Anchor Link

Coloque até 100.000 entradas e 4 MB na requisição como entries. Para uma lista maior, peça um link a POST /uploads, envie o arquivo para esse link com PUT e depois use o upload_id dele. O link dura 2 horas. Não envie sua chave de API para ele.

• Um arquivo é um .txt com uma entrada por linha, de até 200 MB e 10.000.000 de entradas.
• Escreva os números de telefone com o código do país, como +14155550142.
• Os números de telefone de um arquivo deveriam ser de um só país: pelo menos 90% deles. Divida uma lista mista em um arquivo por país.
• Uma única linha inválida faz a lista inteira ser recusada, e a resposta mostra exemplos.
• Um arquivo enviado aguarda um pedido por 24 horas e depois é removido.
• Você pode ter 20 arquivos ou 100 MB aguardando ao mesmo tempo, não importa quantas chaves de API use, e fazer 500 uploads por dia. Um arquivo de qualquer tamanho permitido pode ir além disso quando você estiver abaixo desses limites.

Peça um link

curl -X POST "https://api.talismanleads.io/v1/uploads" \
  -H "Authorization: Bearer tl_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"file_name":"list.txt","size_bytes":1048576}'

Envie o arquivo para ele

UPLOAD_URL="PASTE_upload_url_FROM_THE_ANSWER_ABOVE"
curl --upload-file list.txt "$UPLOAD_URL" \
  -H "Content-Type: text/plain" \
  -w "%{http_code}\n"

3. Veja o preçoCopy Anchor Link

POST /estimates conta as entradas e calcula o preço, sem cobrar nada. billed_entries pode ser maior que entries, pois todo arquivo é faturado como pelo menos 2.000.

curl -X POST "https://api.talismanleads.io/v1/estimates" \
  -H "Authorization: Bearer tl_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"checker":"whatsapp_status_detection","entries":["+14155550142","+12125550187"]}'

4. Faça o pedidoCopy Anchor Link

POST /orders cobra do seu saldo e coloca o trabalho na fila. Envie uma Idempotency-Key, para que uma nova tentativa não possa cobrar duas vezes: veja Novas tentativas seguras. Para ter certeza do preço, envie expected_charge, e o pedido é recusado com price_changed se custar qualquer outro valor. Aguarde até 5 minutos pela resposta, pois ler uma lista grande leva tempo.

curl -X POST "https://api.talismanleads.io/v1/orders" \
  -H "Authorization: Bearer tl_live_your_key_here" \
  -H "Idempotency-Key: crm-export-2026-11-05" \
  -H "Content-Type: application/json" \
  -d '{"checker":"whatsapp_status_detection","entries":["+14155550142","+12125550187"]}'

5. Acompanhe o statusCopy Anchor Link

Consulte GET /orders/{id} com intervalos de 30 segundos ou mais. Um arquivo grande é dividido em partes internamente, mas um pedido tem um único status e um único total.

queued

Aguardando para começar.

processing

Em execução.

completed

Terminado, com todas as partes concluídas.

partially_completed

Terminado, com algumas partes que falharam. Essas partes são reembolsadas: `refunded` mostra o que voltou.

failed

Nenhuma parte pôde ser feita. A cobrança é reembolsada: `refunded` mostra o que voltou.

Mais status podem ser adicionados, então trate um que você não conhece como ainda em execução.

curl "https://api.talismanleads.io/v1/orders/ord_8f2c1e7a-3b4d-4c5e-9f60-1a2b3c4d5e6f" \
  -H "Authorization: Bearer tl_live_your_key_here"

6. Busque o resultadoCopy Anchor Link

GET /orders/{id}/results dá um link de download para cada parte, válido por 15 minutos. Peça um novo link a qualquer momento: os resultados ficam guardados. Um arquivo geralmente é um zip com all.csv, uma planilha e listas de texto, ou um único CSV. Colunas podem ser adicionadas, então leia-as pelo nome, não pela posição. Não envie sua chave de API para esses links.

curl "https://api.talismanleads.io/v1/orders/ord_8f2c1e7a-3b4d-4c5e-9f60-1a2b3c4d5e6f/results" \
  -H "Authorization: Bearer tl_live_your_key_here"

Cobranças e reembolsosCopy Anchor Link

charge é quanto o pedido custou quando você o fez, e refunded é quanto disso voltou. Uma parte que falha é reembolsada integralmente, e em uma parte que o provedor contou a menos a diferença é devolvida, até o mínimo pelo qual a parte é faturada. As duas coisas acontecem automaticamente.

A mesma lista no mesmo verificador em cerca de um dia, com uma nova chave de idempotência, é cobrada de novo como um novo pedido, e pode devolver seu resultado anterior em vez de uma nova verificação.

Pedidos de outros canaisCopy Anchor Link

Os pedidos que você faz no site também aparecem na lista. Os pedidos da API aparecem em Minhas tarefas, no site, com um selo de API, e não enviam nada para o Telegram, a menos que você peça lá.