Placing orders

1. Choose a checkerCopy Anchor Link

GET /checkers lists what your account can order, at your prices. Each has an id, such as whatsapp_status_detection, and takes phones, emails or usernames. See Checkers.

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

2. Send your listCopy Anchor Link

Put up to 100,000 entries and 4 MB in the request as entries. For a larger list, ask POST /uploads for a link, send the file to that link with PUT, then use its upload_id. The link lasts 2 hours. Do not send your API key to it.

• A file is a .txt with one entry on each line, up to 200 MB and 10,000,000 entries.
• Write phone numbers with their country code, such as +14155550142.
• Phone numbers in one file should be from one country: at least 90% of them. Split a mixed list into one file per country.
• One line that is not valid refuses the whole list, and the answer shows examples.
• An uploaded file waits 24 hours for an order, and is then removed.
• You can have 20 files or 100 MB waiting at once, however many keys you use, and make 500 uploads a day. One file of any allowed size can go on top when you are under those.

Ask for a 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}'

Send the file to it

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. See the priceCopy Anchor Link

POST /estimates counts the entries and works out the price, and charges nothing. billed_entries can be more than entries, as every file is billed as at least 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. Place the orderCopy Anchor Link

POST /orders charges your balance and queues the work. Send an Idempotency-Key, so that a retry cannot charge you twice: see Safe retries. To be sure of the price, send expected_charge, and the order is refused with price_changed if it costs anything else. Allow up to 5 minutes for the answer, as a large list takes time to read.

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. Follow its statusCopy Anchor Link

Ask GET /orders/{id} every 30 seconds or more. A large file is split into parts behind the scenes, but an order has one status and one total.

queued

Waiting to start.

processing

Running.

completed

Finished, with every part done.

partially_completed

Finished, with some parts failed. Those parts are refunded: `refunded` shows what came back.

failed

No part could be done. The charge is refunded: `refunded` shows what came back.

More statuses may be added, so treat one you do not know as still running.

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

6. Get the resultCopy Anchor Link

GET /orders/{id}/results gives a download link for each part, good for 15 minutes. Ask again for a new link at any time: results are kept. A file is usually a zip holding all.csv, a spreadsheet and text lists, or a single CSV. Columns can be added, so read them by name rather than by position. Do not send your API key to these links.

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

Charges and refundsCopy Anchor Link

charge is what the order cost when you placed it, and refunded is how much of it came back. A part that fails is refunded in full, and a part the provider counted short has the difference returned, down to the minimum the part is billed at. Both happen automatically.

The same list on the same checker within about a day, under a new key, is charged again as a new order, and can return your earlier result rather than a new check.

Orders from elsewhereCopy Anchor Link

Orders you place on the website are listed too. API orders appear in My Tasks on the website with an API badge, and send nothing to Telegram unless you ask for them there.