Effettuare ordini

1. Scegli un verificatoreCopy Anchor Link

GET /checkers elenca ciò che il tuo account può ordinare, ai tuoi prezzi. Ognuno ha un id, come whatsapp_status_detection, e accetta telefoni, e-mail o nomi utente. Vedi Verificatori.

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

2. Invia la tua listaCopy Anchor Link

Inserisci fino a 100.000 voci e 4 MB nella richiesta come entries. Per una lista più grande, chiedi un link a POST /uploads, invia il file a quel link con PUT, poi usa il suo upload_id. Il link dura 2 ore. Non inviare la tua chiave API a quel link.

• Un file è un .txt con una voce per riga, fino a 200 MB e 10.000.000 di voci.
• Scrivi i numeri di telefono con il prefisso internazionale, come +14155550142.
• I numeri di telefono in un file dovrebbero essere di un solo paese: almeno il 90% di essi. Dividi una lista mista in un file per paese.
• Una sola riga non valida fa rifiutare l’intera lista, e la risposta mostra degli esempi.
• Un file caricato attende un ordine per 24 ore, poi viene rimosso.
• Puoi avere 20 file o 100 MB in attesa contemporaneamente, indipendentemente da quante chiavi API usi, e fare 500 caricamenti al giorno. Quando sei sotto questi limiti, si può aggiungere un file di qualsiasi dimensione consentita.

Chiedi un 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}'

Invia il file a quel link

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. Vedi il prezzoCopy Anchor Link

POST /estimates conta le voci e calcola il prezzo, senza addebitare nulla. billed_entries può essere maggiore di entries, perché ogni file viene fatturato come almeno 2.000 voci.

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. Effettua l’ordineCopy Anchor Link

POST /orders addebita il tuo saldo e mette il lavoro in coda. Invia una Idempotency-Key, così una ripetizione non può addebitarti due volte: vedi Ripetizioni sicure. Per essere sicuro del prezzo, invia expected_charge, e l’ordine viene rifiutato con price_changed se costa qualsiasi altra cifra. Attendi fino a 5 minuti la risposta, perché leggere una lista grande richiede 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. Segui il suo statoCopy Anchor Link

Interroga GET /orders/{id} lasciando 30 secondi o più tra una chiamata e l’altra. Un file grande viene diviso in parti dietro le quinte, ma un ordine ha un solo stato e un solo totale.

queued

In attesa di iniziare.

processing

In esecuzione.

completed

Terminato, con tutte le parti completate.

partially_completed

Terminato, con alcune parti non riuscite. Quelle parti vengono rimborsate: `refunded` mostra ciò che è stato restituito.

failed

Nessuna parte è stata completata. L’addebito viene rimborsato: `refunded` mostra ciò che è stato restituito.

Possono essere aggiunti altri stati, quindi tratta uno stato che non conosci come ancora in esecuzione.

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

6. Recupera il risultatoCopy Anchor Link

GET /orders/{id}/results fornisce un link di download per ogni parte, valido per 15 minuti. Chiedi un nuovo link in qualsiasi momento: i risultati vengono conservati. Un file di solito è uno zip che contiene all.csv, un foglio di calcolo e liste di testo, oppure un singolo CSV. Possono essere aggiunte colonne, quindi leggile per nome e non per posizione. Non inviare la tua chiave API a questi link.

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

Addebiti e rimborsiCopy Anchor Link

charge è quanto è costato l’ordine quando l’hai effettuato, e refunded è quanto ne è stato restituito. Una parte non riuscita viene rimborsata per intero, e per una parte in cui il fornitore ha contato meno voci viene restituita la differenza, fino al minimo fatturato per quella parte. Entrambe le cose avvengono automaticamente.

La stessa lista sullo stesso verificatore entro circa un giorno, con una nuova chiave di idempotenza, viene addebitata di nuovo come nuovo ordine, e può restituire il tuo risultato precedente invece di una nuova verifica.

Ordini effettuati altroveCopy Anchor Link

Anche gli ordini che effettui sul sito web compaiono nell’elenco. Gli ordini API compaiono in Le mie attività sul sito web con un badge API, e non inviano nulla a Telegram a meno che tu non lo chieda lì.