下单
一个订单针对一份列表运行一个检测器。所有检测器的步骤都相同。
1. 选择检测器
GET /checkers 列出您的账户可以订购的检测器及您的价格。每个检测器都有一个 id，例如 whatsapp_status_detection，并接受手机号、邮箱或用户名。请参阅检测器。
curl "https://api.talismanleads.io/v1/checkers" \
-H "Authorization: Bearer tl_live_your_key_here"2. 发送列表
将最多 100,000 条且不超过 4 MB 的记录作为 entries 放入请求。对于更大的列表，请向 POST /uploads 请求一个链接，使用 PUT 将文件发送到该链接，然后使用其 upload_id。链接有效期为 2 小时。不要把 API 密钥发送给该链接。
- 文件为
.txt格式，每行一条记录，最大 200 MB、10,000,000 条。 - 手机号请带国家代码，例如
+14155550142。 - 同一文件中的手机号应来自同一国家：至少 90%。请将混合列表拆分为多个文件，每个国家一个文件。
- 只要有一行无效，整个列表都会被拒绝，响应中会给出示例。
- 已上传的文件会等待下单 24 小时，之后被删除。
- 无论使用多少个 API 密钥，您同时最多可以有 20 个文件或 100 MB 处于等待状态，每天最多上传 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. 查看价格
POST /estimates 统计记录数并计算价格，不会扣费。billed_entries 可能大于 entries，因为每个文件至少按 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. 下单
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. 跟踪状态
请以不少于 30 秒的间隔查询 GET /orders/{id}。大文件会在后台拆分为多个分片，但一个订单只有一个状态和一个总计。
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. 获取结果
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"扣费与退款
charge 是您下单时该订单的费用，refunded 是其中退回的金额。失败的分片全额退款；服务商统计数量偏少的分片会退回差额，但最多退到该分片的最低计费额。两者都会自动进行。
在大约一天内，以新的幂等键在同一检测器上提交同一份列表，会作为新订单再次扣费，并且可能返回您之前的结果，而不是进行新的检测。
来自其他渠道的订单
您在网站上下的订单也会列出。API 订单会显示在网站的「我的任务」中，并带有 API 标记；除非您在 Telegram 上主动请求，否则不会向 Telegram 发送任何内容。