Saltar al contenido
TalismanLeadsDocs
InicioObtener una clave de API

Referencia de la API

La dirección base es https://api.talismanleads.io/v1. Las solicitudes y las respuestas son JSON, salvo los enlaces de subida y de descarga. También está disponible como archivo OpenAPI.

Tu saldo

GET/account

Tu saldo y los límites vigentes.

La clave de API necesita: Solo lectura, o poder realizar pedidos

Ejemplo de solicitud

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

Ejemplo de respuesta (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
  }
}

Listar los verificadores

GET/checkers

Lo que esta cuenta puede pedir ahora mismo, a sus precios. Un verificador en pausa o bloqueado no aparece.

La clave de API necesita: Solo lectura, o poder realizar pedidos

Ejemplo de solicitud

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

Ejemplo de respuesta (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
    }
  ]
}

Subir una lista grande

POST/uploads

Un enlace al que enviar un archivo, directamente al almacenamiento. Envíalo con PUT y los encabezados indicados. El enlace dura 2 horas.

La clave de API necesita: Poder realizar pedidos

Cuerpo

size_bytesinteger · obligatorio
El tamaño del archivo, en bytes.
file_namestring · opcional
Un nombre para la lista, terminado en .txt.

Ejemplo de solicitud

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

Ejemplo de respuesta (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"
}

Ver cuánto costaría un pedido

POST/estimates

Cuenta las entradas, calcula el precio e informa de cualquier problema de la lista. No cobra nada. Espera hasta 5 minutos la respuesta.

La clave de API necesita: Poder realizar pedidos

Cuerpo

checkerstring · obligatorio
El id de un verificador, de GET /checkers.
entriesstring[] · opcional
La lista, una cadena por entrada, de hasta 100.000 entradas y 4 MB. Envía esto o upload_id.
upload_idstring · opcional
Un upload_id de POST /uploads. Envía esto o entries.
countrystring · opcional
Un código de país de dos letras, si quieres indicar de qué país son los números.
file_namestring · opcional
Un nombre para la lista, terminado en .txt.

Ejemplo de solicitud

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

Ejemplo de respuesta (200)

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

Realizar un pedido

POST/orders

Cobra de tu saldo y pone el trabajo en cola. Responde 201 para un pedido nuevo y 200 con Idempotent-Replay: true para una repetición; una repetición en el mismo momento también puede responder 201, así que distingue los pedidos por su id. Espera hasta 5 minutos la respuesta.

La clave de API necesita: Poder realizar pedidos

Encabezados

Idempotency-Keystring · obligatorio
Hasta 200 caracteres ASCII sin espacios. Durante 7 días, la misma clave de idempotencia significa el mismo pedido.

Cuerpo

checkerstring · obligatorio
El id de un verificador, de GET /checkers.
entriesstring[] · opcional
La lista, una cadena por entrada, de hasta 100.000 entradas y 4 MB. Envía esto o upload_id.
upload_idstring · opcional
Un upload_id de POST /uploads. Envía esto o entries.
countrystring · opcional
Un código de país de dos letras, si quieres indicar de qué país son los números.
file_namestring · opcional
Un nombre para la lista, terminado en .txt.
expected_chargestring · opcional
Un precio en dólares, como "18.00". El pedido se rechaza con price_changed si cuesta cualquier otra cantidad.

Ejemplo de solicitud

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

Ejemplo de respuesta (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
}

Listar tus pedidos

GET/orders

Los más recientes primero. Devuelve next_cursor como cursor para obtener la página siguiente.

La clave de API necesita: Solo lectura, o poder realizar pedidos

Parámetros de consulta

limitinteger · opcional
Cuántos devolver, de 1 a 100. El valor predeterminado es 20.
cursorstring · opcional
next_cursor de la última página.

Ejemplo de solicitud

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

Ejemplo de respuesta (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 pedido

GET/orders/{id}

Su estado, entradas, cargo, reembolso, partes y recuentos. results es null hasta que termina una parte, y un recuento es null cuando el verificador no lo informa.

La clave de API necesita: Solo lectura, o poder realizar pedidos

Parámetros de ruta

idstring · obligatorio
El id del pedido.

Ejemplo de solicitud

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

Ejemplo de respuesta (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"
}

Archivos de resultados

GET/orders/{id}/results

Un enlace de descarga por cada parte, válido durante 15 minutos. Una parte aún en ejecución no tiene enlace. Contacta con soporte si una parte completada no lo tiene.

La clave de API necesita: Solo lectura, o poder realizar pedidos

Parámetros de ruta

idstring · obligatorio
El id del pedido.

Ejemplo de solicitud

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

Ejemplo de respuesta (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"
    }
  ]
}

Errores

Anterior

Verificadores

Siguiente

En esta página

Tu saldoListar los verificadoresSubir una lista grandeVer cuánto costaría un pedidoRealizar un pedidoListar tus pedidosUn pedidoArchivos de resultados