Obtener un lead por ID — 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 el detalle completo de un lead a partir de su identificador. Sirve para mostrar un lead dentro de herramientas propias, sincronizar un registro con un CRM externo o leer el estado más reciente antes de ejecutar una acción.

Endpoint

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

Parámetros de ruta

string

requerido

Identificador único del lead. Los IDs llevan el prefijo lead_, por ejemplo lead_abc123. Se obtienen desde Listar leads o desde los payloads de webhook.

Ejemplo de solicitud

cURL

curl https://platform-api.deltalead.ai/v1/leads/lead_abc123 \
  -H "Authorization: Bearer dl_live_YOUR_KEY"

Respuesta

Una solicitud exitosa devuelve HTTP 200 OK con el objeto lead completo. Es la misma forma que devuelve cada elemento de Listar leads.

200 OK

{
  "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": [
    {
      "id": "note_4d7e21",
      "body": "Consultó por financiación a 36 cuotas.",
      "author_id": "user_xyz789",
      "source": "manual",
      "created_at": "2024-03-10T15:02:11Z",
      "updated_at": "2024-03-10T15:02:11Z"
    }
  ],
  "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
}

Campos de la respuesta

string

Identificador único del lead, con el prefijo lead_.

string

Identificador de la organización (concesionario) propietaria del lead.

string

Estado actual dentro del pipeline. Uno de new, contacted, qualified, appointment, proposal, incubating, won, lost.

string

Etiqueta de origen informada por el sistema que generó el lead, por ejemplo landing-page. Es texto libre, siempre viene presente y no reemplaza a channels.

integer

Score de calificación asignado por DeltaLead. Un lead sin calificar tiene 0.

object | null

Datos de contacto de la persona. El nombre, el email y el teléfono viven acá, nunca en el nivel raíz del lead. Es null en un lead que todavía no tiene ningún dato de contacto asociado.

string | null

Nombre de pila.

string | null

Apellido.

string | null

Dirección de email. null si no se conoce.

string | null

Número de teléfono, normalmente en formato E.164. null si no se conoce.

string

Nombre para mostrar, compuesto a partir de first_name y last_name cuando no se informó uno propio.

array of string

Canales por los que el lead se comunicó. Es un arreglo porque un lead los acumula. Valores posibles: typeform, mercadolibre, whatsapp, custom, manual, odoo.

array of string

IDs de los vehículos del catálogo por los que el lead consultó. Son solo identificadores: para los datos del vehículo hay que resolverlos contra el catálogo. La forma es idéntica en Listar leads.

array of string

Etiquetas aplicadas al lead por el equipo.

string | null

ID del vendedor al que está asignado el lead. null si no está asignado.

array of object

Notas del lead, de la más antigua a la más reciente. Siempre es un arreglo de objetos.

string

Identificador de la nota.

string

Texto de la nota.

string

ID de la persona o del proceso que escribió la nota.

string

Origen de la nota. Uno de manual, typeform, legacy, ai_agent, custom_webhook.

string

Marca de tiempo ISO 8601 de creación de la nota.

string | null

Marca de tiempo ISO 8601 de la última edición de la nota. Es null si la nota nunca se editó.

string | null

Resumen de IA de la conversación. Es null mientras ai_summary_status no sea completed.

string

Estado del Resumen de IA. Uno de not_requested, pending, completed, failed.

object

El objeto metadata que la integración envió en Custom Webhook, promovido al nivel raíz del lead y devuelto tal cual. Es el campo que permite confirmar que el payload propio viajó completo y volver a asociar el lead con el registro del sistema de origen. Es {} en un lead que no llegó con metadata.

string | null

Marca de tiempo ISO 8601 de la última interacción registrada para este lead. Es null en un lead que todavía no registró ninguna. Es el campo sobre el que filtran last_activity_after y last_activity_before.

string

Marca de tiempo ISO 8601 de creación del lead.

string

Marca de tiempo ISO 8601 del cambio más reciente en cualquier campo del lead.

string | null

Marca de tiempo ISO 8601 en la que el lead se borra solo. Es siempre null en un lead live: los leads live no expiran. En un lead creado con una clave dl_sandbox_ lleva la fecha de purga automática, así que un lead de sandbox que desaparece está cumpliendo el contrato documentado, no perdiéndose.

Errores

404 — Lead no encontrado

Se devuelve cuando no existe ningún lead con ese id dentro de la organización.

404 Not Found

{
  "status": "error",
  "detail": "lead_not_found"
}

Un ID que pertenece a otra organización devuelve también 404. Conviene ramificar por el identificador de detail, nunca por el texto: ver Errores.

Introducción

Leads

Webhooks

Obtener un lead por ID — endpoint de la API REST de DeltaLead

Endpoint

Parámetros de ruta

Ejemplo de solicitud

Respuesta

Campos de la respuesta

Errores

​Endpoint

​Parámetros de ruta

​Ejemplo de solicitud

​Respuesta

​Campos de la respuesta

​Errores

Endpoint

Parámetros de ruta

Ejemplo de solicitud

Respuesta

Campos de la respuesta

Errores