注文の方法

1. チェッカーを選ぶCopy Anchor Link

GET /checkers は、お客様のアカウントで注文できるものをお客様の料金で一覧表示します。それぞれに id（例：whatsapp_status_detection）があり、電話番号、メール、ユーザー名のいずれかを受け付けます。チェッカーをご覧ください。

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キーを送信しないでください。

• ファイルは 1 行に 1 項目の .txt で、最大 200 MB、10,000,000 件です。
• 電話番号は +14155550142 のように国番号を付けて記述してください。
• 1 つのファイル内の電話番号は 1 つの国のものにしてください（少なくとも 90%）。複数の国が混在するリストは、国ごとに 1 ファイルに分割してください。
• 無効な行が 1 行でもあるとリスト全体が拒否され、レスポンスに例が示されます。
• アップロードされたファイルは注文を 24 時間待ち、その後削除されます。
• 使用する APIキーの数にかかわらず、同時に待機できるのは 20 ファイルまたは 100 MB までで、アップロードは 1 日 500 回までです。これらの上限を下回っているときは、許可されたサイズのファイルをさらに 1 つ追加できます。

リンクを要求する

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 は項目数を数えて料金を算出し、請求は行いません。すべてのファイルは最低 2,000 件分として請求されるため、billed_entries が entries より多くなることがあります。

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 秒以上の間隔で行ってください。大きなファイルは内部で複数のパートに分割されますが、注文のステータスと合計は 1 つです。

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 分間有効なダウンロードリンクを返します。結果は保持されているため、いつでも新しいリンクを要求できます。ファイルは通常、all.csv、スプレッドシート、テキストのリストを含む zip か、単一の 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 はそのうち返金された金額です。失敗したパートは全額返金されます。プロバイダーの集計が少なかったパートは、そのパートの最低請求額を下限として差額が返金されます。どちらも自動で行われます。

同じチェッカーで同じリストを約 1 日以内に新しい冪等キーで送信すると、新しい注文として再度請求され、新しいチェックではなく以前の結果が返されることがあります。

他の場所からの注文Copy Anchor Link

ウェブサイトで行った注文も一覧に含まれます。API の注文はウェブサイトのマイタスクに API バッジ付きで表示され、Telegram で要求しない限り、Telegram には何も送信されません。