Размещение заказов

1. Выберите проверкуCopy Anchor Link

GET /checkers показывает, что может заказать ваш аккаунт, по вашим ценам. У каждой проверки есть id, например whatsapp_status_detection, и она принимает телефоны, email или имена пользователей. См. Проверки.

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

2. Отправьте списокCopy Anchor Link

Передайте в запросе до 100 000 записей и 4 MB в поле entries. Для большего списка запросите ссылку через POST /uploads, отправьте файл на эту ссылку методом PUT, затем используйте его upload_id. Ссылка действует 2 часа. Не отправляйте на неё свой API-ключ.

• Файл: .txt с одной записью в каждой строке, до 200 MB и 10 000 000 записей.
• Указывайте номера телефонов с кодом страны, например +14155550142.
• Номера телефонов в одном файле должны быть из одной страны: не менее 90% из них. Разделите смешанный список на отдельные файлы по странам.
• Одна недействительная строка приводит к отклонению всего списка, а в ответе показаны примеры.
• Загруженный файл ждёт заказа 24 часа, после чего удаляется.
• Одновременно у вас могут ожидать 20 файлов или 100 MB, независимо от количества используемых API-ключей, и вы можете выполнять 500 загрузок в день. Пока вы не достигли этих пределов, сверх них можно добавить один файл любого допустимого размера.

Запросите ссылку

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

Отправьте на неё файл

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. Узнайте ценуCopy Anchor Link

POST /estimates считает записи и рассчитывает цену, ничего не списывая. billed_entries может быть больше entries, так как каждый файл тарифицируется как минимум за 2000.

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. Разместите заказCopy Anchor Link

POST /orders списывает средства с вашего баланса и ставит работу в очередь. Передайте Idempotency-Key, чтобы повтор не мог привести к двойному списанию: см. Безопасные повторы. Для уверенности в цене передайте expected_charge, и заказ будет отклонён с кодом price_changed, если его стоимость окажется любой другой. Закладывайте до 5 минут на ответ, так как чтение большого списка занимает время.

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. Следите за состояниемCopy Anchor Link

Запрашивайте GET /orders/{id} с интервалом не менее 30 секунд. Большой файл незаметно для вас делится на части, но у заказа одно состояние и один итог.

queued

Ожидает запуска.

processing

Выполняется.

completed

Завершён, все части выполнены.

partially_completed

Завершён, некоторые части не удались. Средства за эти части возвращаются: `refunded` показывает, сколько вернулось.

failed

Ни одну часть выполнить не удалось. Списанные средства возвращаются: `refunded` показывает, сколько вернулось.

Могут появиться новые состояния, поэтому считайте незнакомое состояние ещё выполняющимся.

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

6. Получите результатCopy Anchor Link

GET /orders/{id}/results выдаёт ссылку для скачивания по каждой части, действующую 15 минут. Новую ссылку можно запросить в любой момент: результаты сохраняются. Файл обычно представляет собой zip-архив с all.csv, электронной таблицей и текстовыми списками либо один CSV. Столбцы могут добавляться, поэтому читайте их по имени, а не по позиции. Не отправляйте на эти ссылки свой API-ключ.

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

Списания и возвратыCopy Anchor Link

charge показывает, сколько стоил заказ при размещении, а refunded показывает, сколько из этой суммы вернулось. За неудавшуюся часть средства возвращаются полностью, а за часть, которую поставщик насчитал меньше, возвращается разница, но не ниже минимума, по которому тарифицируется эта часть. И то, и другое происходит автоматически.

За тот же список в той же проверке в течение примерно суток с новым Idempotency-Key средства списываются снова, как за новый заказ, и заказ может вернуть ваш прежний результат вместо новой проверки.

Заказы из других местCopy Anchor Link

Заказы, размещённые вами на сайте, тоже попадают в список. Заказы через API появляются на сайте в разделе «Мои задачи» со значком API и ничего не отправляют в Telegram, если вы не запросите это там.