Listar y filtrar leads — endpoint de la API REST de DeltaLead

Este endpoint recupera en una sola respuesta paginada todos los leads captados en los canales conectados: WhatsApp, Meta Ads, MercadoLibre, formularios web, llamadas y email. Los parámetros de consulta que siguen permiten acotar los resultados por estado de calificación, intención de compra, canal de origen, rango de score de IA o fecha de creación, para aislar exactamente el segmento del pipeline que necesita la integración.

Endpoint

GET https://platform-api.deltalead.ai/v1/leads

Parámetros de consulta

integer

predeterminado:"20"

Cantidad máxima de leads a devolver por página. Acepta valores entre 1 y 100.

string

Cursor de paginación opaco devuelto en el campo pagination.next_cursor de la respuesta anterior. Se omite este parámetro para empezar por la primera página.

string

Filtra los leads por su estado actual. Valores aceptados: new, in_conversation, qualified, assigned, closed, lost.

string

Filtra los leads por la intención de compra detectada por la IA. Valores aceptados: purchase_30_days, purchase_90_days, browsing, unknown.

string

Filtra los leads por el canal a través del cual ingresaron por primera vez a DeltaLead. Valores aceptados: whatsapp, facebook, instagram, mercadolibre, web_form, email, phone.

integer

Devuelve solo los leads con un score mayor o igual a este valor. Rango: 0–100.

integer

Devuelve solo los leads con un score menor o igual a este valor. Rango: 0–100.

string

Devuelve solo los leads creados en esta marca de tiempo o después. Debe ser una cadena de fecha y hora ISO 8601, p. ej. 2024-01-15T00:00:00Z.

string

Devuelve solo los leads creados en esta marca de tiempo o antes. Debe ser una cadena de fecha y hora ISO 8601, p. ej. 2024-01-31T23:59:59Z.

Ejemplo de solicitud

cURL

curl 'https://platform-api.deltalead.ai/v1/leads?status=qualified&intent=purchase_30_days&limit=20' \
  -H "X-API-Key: YOUR_API_KEY"

Respuesta

Una solicitud exitosa devuelve HTTP 200 OK con un objeto JSON que contiene un arreglo data de objetos lead y un objeto pagination para la navegación por cursor.

Example response

{
  "data": [
    {
      "id": "lead_abc123",
      "name": "María García",
      "phone": "+5491155551234",
      "email": "maria@example.com",
      "channel": "whatsapp",
      "vehicle_interest": "Toyota Hilux SRX 2024",
      "score": 87,
      "intent": "purchase_30_days",
      "status": "qualified",
      "assigned_to": "user_xyz789",
      "created_at": "2024-03-10T14:22:00Z",
      "updated_at": "2024-03-11T09:05:33Z",
      "last_activity_at": "2024-03-11T09:05:33Z",
      "organization_id": "org_00112233"
    },
    {
      "id": "lead_def456",
      "name": "Carlos Méndez",
      "phone": "+5215512345678",
      "email": null,
      "channel": "mercadolibre",
      "vehicle_interest": "Ford Ranger XLS 2023",
      "score": 74,
      "intent": "purchase_30_days",
      "status": "qualified",
      "assigned_to": null,
      "created_at": "2024-03-10T16:48:10Z",
      "updated_at": "2024-03-10T17:01:55Z",
      "last_activity_at": "2024-03-10T17:01:55Z",
      "organization_id": "org_00112233"
    }
  ],
  "pagination": {
    "total": 148,
    "limit": 20,
    "has_more": true,
    "next_cursor": "cursor_eyJpZCI6ImxlYWRfZGVmNDU2In0"
  }
}

Campos de la respuesta

array

Arreglo de objetos lead que coinciden con los filtros aplicados. La descripción completa de cada campo está en Obtener lead.

string

Identificador único del lead, con el prefijo lead_.

string

Nombre completo del lead tal como se captó desde el canal de origen.

string

Número de teléfono del lead en formato E.164, p. ej. +5491155551234.

string | null

Dirección de email del lead. null si no se proporcionó.

string

Canal por el que el lead contactó por primera vez al concesionario. Uno de whatsapp, facebook, instagram, mercadolibre, web_form, email, phone.

string | null

Modelo o descripción del vehículo por el que el lead manifestó interés. null si todavía no se identificó.

integer

Score de calidad del lead generado por IA, de 0 (frío) a 100 (altamente calificado).

string

Intención de compra detectada. Una de purchase_30_days, purchase_90_days, browsing, unknown.

string

Estado actual del lead dentro de su ciclo de vida. Uno de new, in_conversation, qualified, assigned, closed, lost.

string | null

ID de usuario del asesor de ventas al que está asignado el lead. null si no está asignado.

string

Marca de tiempo ISO 8601 del momento en que se captó el lead.

string

Marca de tiempo ISO 8601 de la actualización de campo más reciente.

string

Marca de tiempo ISO 8601 del último mensaje, llamada o interacción registrada para este lead.

string

Identificador único de la organización de DeltaLead (concesionario) propietaria de este lead.

object

Metadatos de la paginación por cursor.

integer

Cantidad total de leads que coinciden con los filtros aplicados (en todas las páginas).

integer

Cantidad de resultados devueltos en esta página.

boolean

true si existen páginas adicionales de resultados.

string | null

Este valor se pasa como parámetro de consulta cursor para obtener la página siguiente. Es null cuando has_more es false.

Para armar un pipeline de sincronización eficiente, conviene combinar created_after con un cursor almacenado. Se hace una primera consulta con created_after en la marca de tiempo de la última sincronización y luego se pagina con next_cursor hasta que has_more sea false.

Introducción

Leads

Conversaciones

Agentes

Webhooks

Listar y filtrar leads — endpoint de la API REST de DeltaLead

Endpoint

Parámetros de consulta

Ejemplo de solicitud

Respuesta

Campos de la respuesta

​Endpoint

​Parámetros de consulta

​Ejemplo de solicitud

​Respuesta

​Campos de la respuesta

Endpoint

Parámetros de consulta

Ejemplo de solicitud

Respuesta

Campos de la respuesta