Vai al contenuto
TalismanLeadsDocs
HomeOttieni una chiave API

Riferimento API

L’indirizzo base è https://api.talismanleads.io/v1. Richieste e risposte sono in JSON, tranne i link di caricamento e di download. Disponibile anche come file OpenAPI.

Il tuo saldo

GET/account

Il tuo saldo e i limiti in vigore.

La chiave API deve essere: Di sola lettura, o in grado di effettuare ordini

Esempio di richiesta

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

Esempio di risposta (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
  }
}

Elenca i verificatori

GET/checkers

Ciò che questo account può ordinare ora, ai suoi prezzi. Un verificatore in pausa o bloccato non viene elencato.

La chiave API deve essere: Di sola lettura, o in grado di effettuare ordini

Esempio di richiesta

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

Esempio di risposta (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
    }
  ]
}

Carica una lista grande

POST/uploads

Un link a cui inviare un file, direttamente allo storage. Invialo con PUT e le intestazioni indicate. Il link dura 2 ore.

La chiave API deve essere: In grado di effettuare ordini

Corpo

size_bytesinteger · obbligatorio
La dimensione del file, in byte.
file_namestring · facoltativo
Un nome per la lista, che termini con .txt.

Esempio di richiesta

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

Esempio di risposta (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"
}

Vedi quanto costerebbe un ordine

POST/estimates

Conta le voci, calcola il prezzo e segnala qualsiasi problema della lista. Non addebita nulla. Attendi fino a 5 minuti la risposta.

La chiave API deve essere: In grado di effettuare ordini

Corpo

checkerstring · obbligatorio
L’id di un verificatore, da GET /checkers.
entriesstring[] · facoltativo
La lista, una stringa per voce, fino a 100.000 voci e 4 MB. Invia questo oppure upload_id.
upload_idstring · facoltativo
Un upload_id da POST /uploads. Invia questo oppure entries.
countrystring · facoltativo
Un codice paese di due lettere, se vuoi indicare di quale paese sono i numeri.
file_namestring · facoltativo
Un nome per la lista, che termini con .txt.

Esempio di richiesta

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

Esempio di risposta (200)

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

Effettua un ordine

POST/orders

Addebita il tuo saldo e mette il lavoro in coda. Risponde 201 per un nuovo ordine e 200 con Idempotent-Replay: true per una ripetizione; una ripetizione nello stesso momento può rispondere anche 201, quindi distingui gli ordini in base a id. Attendi fino a 5 minuti la risposta.

La chiave API deve essere: In grado di effettuare ordini

Intestazioni

Idempotency-Keystring · obbligatorio
Fino a 200 caratteri ASCII senza spazi. Per 7 giorni la stessa chiave di idempotenza indica lo stesso ordine.

Corpo

checkerstring · obbligatorio
L’id di un verificatore, da GET /checkers.
entriesstring[] · facoltativo
La lista, una stringa per voce, fino a 100.000 voci e 4 MB. Invia questo oppure upload_id.
upload_idstring · facoltativo
Un upload_id da POST /uploads. Invia questo oppure entries.
countrystring · facoltativo
Un codice paese di due lettere, se vuoi indicare di quale paese sono i numeri.
file_namestring · facoltativo
Un nome per la lista, che termini con .txt.
expected_chargestring · facoltativo
Un prezzo in dollari, come "18.00". L’ordine viene rifiutato con price_changed se costa qualsiasi altra cifra.

Esempio di richiesta

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

Esempio di risposta (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
}

Elenca i tuoi ordini

GET/orders

Prima i più recenti. Ripassa next_cursor come cursor per la pagina successiva.

La chiave API deve essere: Di sola lettura, o in grado di effettuare ordini

Parametri di query

limitinteger · facoltativo
Quanti risultati restituire, da 1 a 100. Il valore predefinito è 20.
cursorstring · facoltativo
next_cursor dell’ultima pagina.

Esempio di richiesta

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

Esempio di risposta (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
}

Un ordine

GET/orders/{id}

Stato, voci, addebito, rimborso, parti e conteggi. results è null finché una parte non termina, e un conteggio è null quando il verificatore non lo riporta.

La chiave API deve essere: Di sola lettura, o in grado di effettuare ordini

Parametri di percorso

idstring · obbligatorio
L’id dell’ordine.

Esempio di richiesta

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

Esempio di risposta (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"
}

File dei risultati

GET/orders/{id}/results

Un link di download per ogni parte, valido per 15 minuti. Una parte ancora in esecuzione non ha un link. Contatta l’assistenza se una parte completata non ne ha uno.

La chiave API deve essere: Di sola lettura, o in grado di effettuare ordini

Parametri di percorso

idstring · obbligatorio
L’id dell’ordine.

Esempio di richiesta

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

Esempio di risposta (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"
    }
  ]
}

Errori

Precedente

Verificatori

Successiva

In questa pagina

Il tuo saldoElenca i verificatoriCarica una lista grandeVedi quanto costerebbe un ordineEffettua un ordineElenca i tuoi ordiniUn ordineFile dei risultati