本文へスキップ
TalismanLeadsDocs
ホームAPIキーを取得

API リファレンス

ベース URL は https://api.talismanleads.io/v1 です。アップロードリンクとダウンロードリンクを除き、リクエストとレスポンスは JSON です。OpenAPI ファイルも利用できます。

残高

GET/account

残高と現在適用されている制限。

必要な APIキー: 読み取り専用または注文可能

リクエスト例

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

レスポンス例 (200)

{
  "balance": "100.00",
  "currency": "USD",
  "key": {
    "id": "11111111-1111-4111-8111-111111111111",
    "scopes": [
      "read",
      "orders"
    ]
  },
  "limits": {
    "reads_per_minute": 60,
    "result_downloads_per_minute": 30,
    "uploads_per_minute": 10,
    "estimates_per_minute": 10,
    "orders_per_minute": 10,
    "open_task_parts": 20
  }
}

チェッカーの一覧

GET/checkers

このアカウントで現在注文できるものを、その料金で表示します。一時停止中またはブロックされたチェッカーは表示されません。

必要な APIキー: 読み取り専用または注文可能

リクエスト例

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

レスポンス例 (200)

{
  "checkers": [
    {
      "id": "whatsapp_status_detection",
      "name": "WhatsApp Status Detection",
      "input": "phone",
      "price": {
        "amount": "3.00",
        "per_entries": 10000,
        "currency": "USD"
      },
      "minimum_entries": 0,
      "minimum_billed_entries": 2000,
      "calling_code": null
    }
  ]
}

大きなリストのアップロード

POST/uploads

ファイルをストレージに直接送信するためのリンクです。PUT と指定されたヘッダーで送信してください。リンクの有効期間は 2 時間です。

必要な APIキー: 注文可能

ボディ

size_bytesinteger · 必須
ファイルのサイズ（バイト）。
file_namestring · 任意
リストの名前。末尾は .txt です。

リクエスト例

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

レスポンス例 (201)

{
  "upload_id": "upl_2b7d9f10-6c3e-4a1f-8d2b-9e8f7a6b5c4d",
  "upload_url": "https://storage.example.com/upload/sign/list.txt?token=...",
  "method": "PUT",
  "headers": {
    "Content-Type": "text/plain"
  },
  "expires_at": "2026-11-05T11:00:00.000Z"
}

注文の料金を確認

POST/estimates

項目数を数え、料金を算出し、リストの問題点を報告します。請求は発生しません。レスポンスには最大 5 分を見込んでください。

必要な APIキー: 注文可能

ボディ

checkerstring · 必須
GET /checkers から取得したチェッカーの id。
entriesstring[] · 任意
リスト。1 項目につき 1 つの文字列で、100,000 件以内かつ 4 MB 以内です。これか upload_id のどちらかを送信してください。
upload_idstring · 任意
POST /uploads から取得した upload_id。これか entries のどちらかを送信してください。
countrystring · 任意
番号の国を指定する場合の 2 文字の国コード。
file_namestring · 任意
リストの名前。末尾は .txt です。

リクエスト例

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

レスポンス例 (200)

{
  "checker": "whatsapp_status_detection",
  "entries": 2,
  "billed_entries": 2000,
  "charge": "0.60",
  "currency": "USD",
  "parts": 1,
  "country": {
    "code": "US",
    "share": 1
  }
}

注文する

POST/orders

残高に請求し、処理をキューに入れます。新しい注文には 201、繰り返しには 200 と Idempotent-Replay: true を返します。同時の繰り返しでも 201 が返ることがあるため、注文は id で区別してください。レスポンスには最大 5 分を見込んでください。

必要な APIキー: 注文可能

ヘッダー

Idempotency-Keystring · 必須
スペースを含まない 200 文字以内の ASCII 文字列。7 日間は同じ冪等キーが同じ注文を意味します。

ボディ

checkerstring · 必須
GET /checkers から取得したチェッカーの id。
entriesstring[] · 任意
リスト。1 項目につき 1 つの文字列で、100,000 件以内かつ 4 MB 以内です。これか upload_id のどちらかを送信してください。
upload_idstring · 任意
POST /uploads から取得した upload_id。これか entries のどちらかを送信してください。
countrystring · 任意
番号の国を指定する場合の 2 文字の国コード。
file_namestring · 任意
リストの名前。末尾は .txt です。
expected_chargestring · 任意
ドル建ての料金（例："18.00"）。料金がこれと少しでも異なる場合、注文は price_changed で拒否されます。

リクエスト例

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

レスポンス例 (201)

{
  "id": "ord_8f2c1e7a-3b4d-4c5e-9f60-1a2b3c4d5e6f",
  "checker": "whatsapp_status_detection",
  "status": "queued",
  "entries": 2,
  "charge": "0.60",
  "refunded": "0.00",
  "currency": "USD",
  "parts": {
    "total": 1,
    "completed": 0,
    "failed": 0
  },
  "results": null,
  "error": null,
  "source": "api",
  "created_at": "2026-11-05T09:00:00.000Z",
  "completed_at": null
}

注文の一覧

GET/orders

新しい順です。次のページを取得するには next_cursor を cursor として渡してください。

必要な APIキー: 読み取り専用または注文可能

クエリパラメーター

limitinteger · 任意
返す件数（1〜100）。デフォルトは 20 です。
cursorstring · 任意
前のページの next_cursor。

リクエスト例

curl "https://api.talismanleads.io/v1/orders?limit=20" \
  -H "Authorization: Bearer tl_live_your_key_here"

レスポンス例 (200)

{
  "orders": [
    {
      "id": "ord_8f2c1e7a-3b4d-4c5e-9f60-1a2b3c4d5e6f",
      "checker": "whatsapp_status_detection",
      "status": "completed",
      "entries": 2,
      "charge": "0.60",
      "refunded": "0.00",
      "currency": "USD",
      "parts": {
        "total": 1,
        "completed": 1,
        "failed": 0
      },
      "results": {
        "registered": 1,
        "not_registered": 1
      },
      "error": null,
      "source": "api",
      "created_at": "2026-11-05T09:00:00.000Z",
      "completed_at": "2026-11-05T09:02:10.000Z"
    }
  ],
  "next_cursor": null
}

1 件の注文

GET/orders/{id}

ステータス、項目数、請求額、返金、パート、カウント。パートが完了するまで results は null で、チェッカーが報告しないカウントは null です。

必要な APIキー: 読み取り専用または注文可能

パスパラメーター

idstring · 必須
注文の id。

リクエスト例

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

レスポンス例 (200)

{
  "id": "ord_8f2c1e7a-3b4d-4c5e-9f60-1a2b3c4d5e6f",
  "checker": "whatsapp_status_detection",
  "status": "completed",
  "entries": 2,
  "charge": "0.60",
  "refunded": "0.00",
  "currency": "USD",
  "parts": {
    "total": 1,
    "completed": 1,
    "failed": 0
  },
  "results": {
    "registered": 1,
    "not_registered": 1
  },
  "error": null,
  "source": "api",
  "created_at": "2026-11-05T09:00:00.000Z",
  "completed_at": "2026-11-05T09:02:10.000Z"
}

結果ファイル

GET/orders/{id}/results

パートごとに 15 分間有効なダウンロードリンク。実行中のパートにはリンクがありません。完了したパートにリンクがない場合は、サポートにお問い合わせください。

必要な APIキー: 読み取り専用または注文可能

パスパラメーター

idstring · 必須
注文の id。

リクエスト例

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

レスポンス例 (200)

{
  "order_id": "ord_8f2c1e7a-3b4d-4c5e-9f60-1a2b3c4d5e6f",
  "status": "completed",
  "parts": [
    {
      "part": 1,
      "status": "completed",
      "file_name": "result.csv",
      "url": "https://storage.example.com/sign/result.csv?token=...",
      "expires_at": "2026-11-05T09:17:10.000Z"
    }
  ]
}

エラー

前へ

チェッカー

次へ

このページの内容

残高チェッカーの一覧大きなリストのアップロード注文の料金を確認注文する注文の一覧1 件の注文結果ファイル