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

La API REST está en acceso anticipado y se habilita por cuenta a pedido. Las claves de API no se emiten todavía desde el panel. Para solicitar acceso, contactar al ejecutivo de cuenta.

Este endpoint devuelve los leads de la organización en una respuesta paginada por cursor. Los parámetros de consulta acotan el resultado por estado, canal y rango de última actividad, para aislar el segmento del pipeline que necesita la integración.

Endpoint

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

Parámetros de consulta

string

Filtra por estado actual del lead. El conjunto es cerrado: new, contacted, qualified, appointment, proposal, incubating, won, lost. Un valor fuera de esa lista devuelve 422, no un resultado vacío.

string

Devuelve los leads que acumularon este canal. El conjunto es cerrado: typeform, mercadolibre, whatsapp, custom, manual, odoo. Un valor fuera de esa lista devuelve 422, no un resultado vacío.

string

Devuelve solo los leads cuya last_activity_at sea igual o posterior a esta marca de tiempo. El límite es inclusivo. Cadena de fecha y hora ISO 8601, por ejemplo 2024-01-15T00:00:00Z. Filtra por última actividad, no por fecha de creación.

string

Devuelve solo los leads cuya last_activity_at sea igual o anterior a esta marca de tiempo. El límite es inclusivo. Cadena de fecha y hora ISO 8601, por ejemplo 2024-01-31T23:59:59Z. Filtra por última actividad, no por fecha de creación.

string

Cursor de paginación devuelto en next_cursor por la respuesta anterior. Se omite para empezar por la primera página. El valor es opaco: no se parsea ni se construye.

integer

predeterminado:"20"

Cantidad máxima de leads por página. Entero entre 1 y 100.

No hay filtros por score, por vehículo del catálogo ni por texto libre: los seis parámetros de arriba son los únicos que acepta el endpoint.

Ejemplo de solicitud

cURL

curl 'https://platform-api.deltalead.ai/v1/leads?status=qualified&channel=whatsapp&last_activity_after=2024-03-01T00:00:00Z&limit=20' \
  -H "Authorization: Bearer dl_live_YOUR_KEY"

Respuesta

Una solicitud exitosa devuelve HTTP 200 OK con el arreglo data y los dos campos de paginación en el nivel raíz.

200 OK

{
  "data": [
    {
      "id": "lead_abc123",
      "organization_id": "org_00112233",
      "status": "qualified",
      "source": "landing-page",
      "score": 87,
      "contact": {
        "first_name": "María",
        "last_name": "García",
        "email": "maria@example.com",
        "phone": "+5491155551234",
        "display_name": "María García"
      },
      "channels": ["whatsapp", "custom"],
      "interested_vehicles": ["veh_9f2c41"],
      "tags": ["financiacion"],
      "assigned_to": "user_xyz789",
      "notes": [],
      "ai_summary": "Consulta por una Hilux SRX 2024 con financiación a 36 cuotas. Pidió que la contacten por la tarde.",
      "ai_summary_status": "completed",
      "metadata": {
        "crm_id": "CRM-88213",
        "utm_campaign": "hilux-marzo"
      },
      "last_activity_at": "2024-03-11T09:05:33Z",
      "created_at": "2024-03-10T14:22:00Z",
      "updated_at": "2024-03-11T09:05:33Z",
      "expire_at": null
    },
    {
      "id": "lead_def456",
      "organization_id": "org_00112233",
      "status": "new",
      "source": "mercadolibre",
      "score": 0,
      "contact": {
        "first_name": "Carlos",
        "last_name": "Méndez",
        "email": null,
        "phone": "+5215512345678",
        "display_name": "Carlos Méndez"
      },
      "channels": ["mercadolibre"],
      "interested_vehicles": [],
      "tags": [],
      "assigned_to": null,
      "notes": [],
      "ai_summary": null,
      "ai_summary_status": "not_requested",
      "metadata": {},
      "last_activity_at": "2024-03-10T17:01:55Z",
      "created_at": "2024-03-10T16:48:10Z",
      "updated_at": "2024-03-10T17:01:55Z",
      "expire_at": null
    }
  ],
  "next_cursor": "cursor_eyJpZCI6ImxlYWRfZGVmNDU2In0",
  "has_more": true
}

Campos de la respuesta

array

Leads que coinciden con los filtros aplicados, del más reciente al más antiguo. Cada elemento tiene exactamente la misma forma que devuelve Obtener lead, campo por campo.

string | null

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

boolean

true si existen páginas adicionales de resultados.

La respuesta no incluye un total: contarlo exige una segunda consulta sobre el mismo filtro en cada página. Para recorrer todo el resultado, se pagina hasta que has_more sea false.

Para una sincronización incremental, conviene combinar last_activity_after con un cursor almacenado: una primera consulta con last_activity_after en la marca de tiempo de la última sincronización y después next_cursor hasta agotar el resultado. Al filtrar por última actividad y no por creación, la sincronización también levanta los leads antiguos que volvieron a moverse.

Introducción

Leads

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