跳到正文
TalismanLeadsDocs
首页获取 API 密钥

API 参考

基础地址是 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[] · 可选
列表，每条记录一个字符串，最多 100,000 条且不超过 4 MB。发送此项或 upload_id。
upload_idstring · 可选
来自 POST /uploads 的 upload_id。发送此项或 entries。
countrystring · 可选
两个字母的国家代码，如果您想说明号码来自哪个国家。
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[] · 可选
列表，每条记录一个字符串，最多 100,000 条且不超过 4 MB。发送此项或 upload_id。
upload_idstring · 可选
来自 POST /uploads 的 upload_id。发送此项或 entries。
countrystring · 可选
两个字母的国家代码，如果您想说明号码来自哪个国家。
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
}

单个订单

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

错误

上一页

检测器

下一页

本页内容

您的余额列出检测器上传大型列表查看订单费用下单列出您的订单单个订单结果文件