Chuyển đến nội dung
TalismanLeadsDocs
Trang chủLấy khóa API

Tham chiếu API

Địa chỉ gốc là https://api.talismanleads.io/v1. Yêu cầu và phản hồi đều là JSON, trừ các liên kết tải lên và tải xuống. Cũng có sẵn dưới dạng tệp OpenAPI.

Số dư của bạn

GET/account

Số dư của bạn và các giới hạn đang áp dụng.

Khóa API cần có: Chỉ đọc, hoặc có thể đặt đơn hàng

Yêu cầu mẫu

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

Phản hồi mẫu (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
  }
}

Liệt kê các trình kiểm tra

GET/checkers

Những gì tài khoản này có thể đặt ngay bây giờ, theo giá của tài khoản. Trình kiểm tra đang tạm dừng hoặc bị chặn không được liệt kê.

Khóa API cần có: Chỉ đọc, hoặc có thể đặt đơn hàng

Yêu cầu mẫu

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

Phản hồi mẫu (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
    }
  ]
}

Tải lên danh sách lớn

POST/uploads

Một liên kết để gửi tệp, thẳng đến nơi lưu trữ. Hãy gửi bằng PUT và các header được cung cấp. Liên kết có hiệu lực trong 2 giờ.

Khóa API cần có: Có thể đặt đơn hàng

Nội dung yêu cầu

size_bytesinteger · bắt buộc
Kích thước của tệp, tính bằng byte.
file_namestring · tùy chọn
Tên của danh sách, kết thúc bằng .txt.

Yêu cầu mẫu

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

Phản hồi mẫu (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"
}

Xem chi phí của đơn hàng

POST/estimates

Đếm các mục, tính giá và báo cáo mọi vấn đề của danh sách. Không tính phí. Hãy chờ tối đa 5 phút cho phản hồi.

Khóa API cần có: Có thể đặt đơn hàng

Nội dung yêu cầu

checkerstring · bắt buộc
id của trình kiểm tra từ GET /checkers.
entriesstring[] · tùy chọn
Danh sách, mỗi mục một chuỗi, tối đa 100.000 mục và 4 MB. Gửi trường này hoặc upload_id.
upload_idstring · tùy chọn
upload_id từ POST /uploads. Gửi trường này hoặc entries.
countrystring · tùy chọn
Mã quốc gia hai chữ cái, nếu bạn muốn cho biết các số thuộc quốc gia nào.
file_namestring · tùy chọn
Tên của danh sách, kết thúc bằng .txt.

Yêu cầu mẫu

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

Phản hồi mẫu (200)

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

Đặt đơn hàng

POST/orders

Trừ tiền vào số dư của bạn và đưa công việc vào hàng đợi. Trả về 201 cho đơn hàng mới, và 200 kèm Idempotent-Replay: true cho lần lặp lại; lần lặp lại vào cùng một thời điểm cũng có thể trả về 201, vì vậy hãy phân biệt các đơn hàng bằng id. Hãy chờ tối đa 5 phút cho phản hồi.

Khóa API cần có: Có thể đặt đơn hàng

Header

Idempotency-Keystring · bắt buộc
Tối đa 200 ký tự ASCII không có khoảng trắng. Trong 7 ngày, cùng một khóa idempotency nghĩa là cùng một đơn hàng.

Nội dung yêu cầu

checkerstring · bắt buộc
id của trình kiểm tra từ GET /checkers.
entriesstring[] · tùy chọn
Danh sách, mỗi mục một chuỗi, tối đa 100.000 mục và 4 MB. Gửi trường này hoặc upload_id.
upload_idstring · tùy chọn
upload_id từ POST /uploads. Gửi trường này hoặc entries.
countrystring · tùy chọn
Mã quốc gia hai chữ cái, nếu bạn muốn cho biết các số thuộc quốc gia nào.
file_namestring · tùy chọn
Tên của danh sách, kết thúc bằng .txt.
expected_chargestring · tùy chọn
Giá tính bằng đô la, ví dụ "18.00". Đơn hàng sẽ bị từ chối với price_changed nếu chi phí khác đi dù chỉ một chút.

Yêu cầu mẫu

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

Phản hồi mẫu (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
}

Liệt kê đơn hàng của bạn

GET/orders

Mới nhất trước. Truyền next_cursor trở lại dưới dạng cursor để lấy trang tiếp theo.

Khóa API cần có: Chỉ đọc, hoặc có thể đặt đơn hàng

Tham số truy vấn

limitinteger · tùy chọn
Số lượng trả về, từ 1 đến 100. Mặc định là 20.
cursorstring · tùy chọn
next_cursor từ trang trước.

Yêu cầu mẫu

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

Phản hồi mẫu (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
}

Một đơn hàng

GET/orders/{id}

Trạng thái, số mục, phí, hoàn tiền, các phần và số đếm của đơn hàng. results là null cho đến khi có một phần hoàn tất, và số đếm là null khi trình kiểm tra không báo cáo.

Khóa API cần có: Chỉ đọc, hoặc có thể đặt đơn hàng

Tham số đường dẫn

idstring · bắt buộc
id của đơn hàng.

Yêu cầu mẫu

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

Phản hồi mẫu (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"
}

Tệp kết quả

GET/orders/{id}/results

Một liên kết tải xuống cho mỗi phần, có hiệu lực trong 15 phút. Phần đang chạy không có liên kết. Hãy liên hệ bộ phận hỗ trợ nếu một phần đã hoàn tất không có liên kết.

Khóa API cần có: Chỉ đọc, hoặc có thể đặt đơn hàng

Tham số đường dẫn

idstring · bắt buộc
id của đơn hàng.

Yêu cầu mẫu

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

Phản hồi mẫu (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"
    }
  ]
}

Lỗi

Trước

Trình kiểm tra

Tiếp

Trên trang này

Số dư của bạnLiệt kê các trình kiểm traTải lên danh sách lớnXem chi phí của đơn hàngĐặt đơn hàngLiệt kê đơn hàng của bạnMột đơn hàngTệp kết quả