Довідник 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 · обов’язковий: id перевірки з GET /checkers.
entriesstring[] · необов’язковий: Список, по одному рядку на запис, до 100 000 записів і 4 MB. Передайте це поле або upload_id.
upload_idstring · необов’язковий: upload_id з POST /uploads. Передайте це поле або 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
  }
}

Списує кошти з вашого балансу й ставить роботу в чергу. Відповідає 201 на нове замовлення і 200 з Idempotent-Replay: true на повтор; повтор у той самий момент також може отримати відповідь 201, тому розрізняйте замовлення за id. Закладайте до 5 хвилин на відповідь.

Потрібен API-ключ: З розміщенням замовлень

Заголовки

Idempotency-Keystring · обов’язковий: До 200 символів ASCII без пробілів. Протягом 7 днів той самий Idempotency-Key означає те саме замовлення.

Тіло

checkerstring · обов’язковий: id перевірки з GET /checkers.
entriesstring[] · необов’язковий: Список, по одному рядку на запис, до 100 000 записів і 4 MB. Передайте це поле або upload_id.
upload_idstring · необов’язковий: upload_id з POST /uploads. Передайте це поле або 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"
    }
  ]
}

Довідник API

Ваш баланс

Приклад запиту

Приклад відповіді (200)

Список перевірок

Приклад запиту

Приклад відповіді (200)

Завантаження великого списку

Тіло

Приклад запиту

Приклад відповіді (201)

Дізнатися, скільки коштуватиме замовлення

Тіло

Приклад запиту

Приклад відповіді (200)

Розмістити замовлення

Заголовки

Тіло

Приклад запиту

Приклад відповіді (201)

Список ваших замовлень

Параметри запиту

Приклад запиту

Приклад відповіді (200)

Одне замовлення

Параметри шляху

Приклад запиту

Приклад відповіді (200)

Файли з результатами

Параметри шляху

Приклад запиту

Приклад відповіді (200)

На цій сторінці

Довідник API

Ваш балансCopy Anchor Link

Приклад запиту

Приклад відповіді (200)

Список перевірокCopy Anchor Link

Приклад запиту

Приклад відповіді (200)

Завантаження великого спискуCopy Anchor Link

Тіло

Приклад запиту

Приклад відповіді (201)

Дізнатися, скільки коштуватиме замовленняCopy Anchor Link

Тіло

Приклад запиту

Приклад відповіді (200)

Розмістити замовленняCopy Anchor Link

Заголовки

Тіло

Приклад запиту

Приклад відповіді (201)

Список ваших замовленьCopy Anchor Link

Параметри запиту

Приклад запиту

Приклад відповіді (200)

Одне замовленняCopy Anchor Link

Параметри шляху

Приклад запиту

Приклад відповіді (200)

Файли з результатамиCopy Anchor Link

Параметри шляху

Приклад запиту

Приклад відповіді (200)

На цій сторінці

Ваш баланс

Список перевірок

Завантаження великого списку

Дізнатися, скільки коштуватиме замовлення

Розмістити замовлення

Список ваших замовлень

Одне замовлення

Файли з результатами