Aller au contenu
TalismanLeadsDocs
AccueilObtenir une clé API

Référence de l’API

L’adresse de base est https://api.talismanleads.io/v1. Les requêtes et les réponses sont en JSON, sauf les liens d’importation et de téléchargement. Également disponible sous forme de fichier OpenAPI.

Votre solde

GET/account

Votre solde et les limites en vigueur.

La clé API doit être: En lecture seule, ou autorisée à passer des commandes

Exemple de requête

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

Exemple de réponse (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
  }
}

Lister les vérificateurs

GET/checkers

Ce que ce compte peut commander en ce moment, à ses prix. Un vérificateur en pause ou bloqué n’est pas listé.

La clé API doit être: En lecture seule, ou autorisée à passer des commandes

Exemple de requête

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

Exemple de réponse (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
    }
  ]
}

Importer une grande liste

POST/uploads

Un lien auquel envoyer un fichier, directement vers le stockage. Envoyez-le avec PUT et les en-têtes indiqués. Le lien est valable 2 heures.

La clé API doit être: Autorisée à passer des commandes

Corps

size_bytesinteger · obligatoire
La taille du fichier, en octets.
file_namestring · facultatif
Un nom pour la liste, se terminant par .txt.

Exemple de requête

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

Exemple de réponse (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"
}

Voir ce que coûterait une commande

POST/estimates

Compte les entrées, calcule le prix et signale tout problème dans la liste. Ne débite rien. Prévoyez jusqu’à 5 minutes pour la réponse.

La clé API doit être: Autorisée à passer des commandes

Corps

checkerstring · obligatoire
L’id d’un vérificateur, issu de GET /checkers.
entriesstring[] · facultatif
La liste, une chaîne par entrée, jusqu’à 100 000 entrées et 4 MB. Envoyez ceci ou upload_id.
upload_idstring · facultatif
Un upload_id issu de POST /uploads. Envoyez ceci ou entries.
countrystring · facultatif
Un code de pays à deux lettres, si vous souhaitez indiquer de quel pays proviennent les numéros.
file_namestring · facultatif
Un nom pour la liste, se terminant par .txt.

Exemple de requête

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

Exemple de réponse (200)

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

Passer une commande

POST/orders

Débite votre solde et met le travail en file d’attente. Répond 201 pour une nouvelle commande, et 200 avec Idempotent-Replay: true pour une répétition ; une répétition au même moment peut aussi répondre 201, distinguez donc les commandes par leur id. Prévoyez jusqu’à 5 minutes pour la réponse.

La clé API doit être: Autorisée à passer des commandes

En-têtes

Idempotency-Keystring · obligatoire
Jusqu’à 200 caractères ASCII sans espaces. Pendant 7 jours, la même clé d’idempotence désigne la même commande.

Corps

checkerstring · obligatoire
L’id d’un vérificateur, issu de GET /checkers.
entriesstring[] · facultatif
La liste, une chaîne par entrée, jusqu’à 100 000 entrées et 4 MB. Envoyez ceci ou upload_id.
upload_idstring · facultatif
Un upload_id issu de POST /uploads. Envoyez ceci ou entries.
countrystring · facultatif
Un code de pays à deux lettres, si vous souhaitez indiquer de quel pays proviennent les numéros.
file_namestring · facultatif
Un nom pour la liste, se terminant par .txt.
expected_chargestring · facultatif
Un prix en dollars, comme "18.00". La commande est refusée avec price_changed si elle coûte un autre montant.

Exemple de requête

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

Exemple de réponse (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
}

Lister vos commandes

GET/orders

Les plus récentes d’abord. Renvoyez next_cursor en tant que cursor pour obtenir la page suivante.

La clé API doit être: En lecture seule, ou autorisée à passer des commandes

Paramètres de requête

limitinteger · facultatif
Le nombre d’éléments à renvoyer, de 1 à 100. La valeur par défaut est 20.
cursorstring · facultatif
next_cursor de la dernière page.

Exemple de requête

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

Exemple de réponse (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
}

Une commande

GET/orders/{id}

Son état, ses entrées, son débit, son remboursement, ses parties et ses décomptes. results vaut null jusqu’à ce qu’une partie soit terminée, et un décompte vaut null lorsque le vérificateur ne le communique pas.

La clé API doit être: En lecture seule, ou autorisée à passer des commandes

Paramètres de chemin

idstring · obligatoire
L’id de la commande.

Exemple de requête

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

Exemple de réponse (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"
}

Fichiers de résultats

GET/orders/{id}/results

Un lien de téléchargement pour chaque partie, valable 15 minutes. Une partie encore en cours n’a pas de lien. Contactez l’assistance si une partie terminée n’en a pas.

La clé API doit être: En lecture seule, ou autorisée à passer des commandes

Paramètres de chemin

idstring · obligatoire
L’id de la commande.

Exemple de requête

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

Exemple de réponse (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"
    }
  ]
}

Erreurs

Précédent

Vérificateurs

Suivant

Sur cette page

Votre soldeLister les vérificateursImporter une grande listeVoir ce que coûterait une commandePasser une commandeLister vos commandesUne commandeFichiers de résultats