> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deltalead.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Crear un lead por API — referencia de la API REST de DeltaLead

> Agregar un lead a DeltaLead sin interacción por canal: ideal para importar sistemas heredados, formularios propios o fuentes de terceros sin integración nativa.

Este endpoint crea un registro de lead nuevo en DeltaLead de forma programática, sin que el contacto tenga que llegar por uno de los canales conectados. Es el endpoint indicado para importar contactos desde una base de datos heredada, enviar los envíos de un formulario de captación propio o derivar leads desde una fuente de terceros sin integración nativa. Una vez creado, el lead aparece de inmediato en el Inbox unificado y queda habilitado para la calificación por IA, los flujos de asignación y las campañas salientes.

## Endpoint

```text theme={null}
POST https://platform-api.deltalead.ai/v1/leads
```

## Cuerpo de la solicitud

<ParamField body="name" type="string" required>
  Nombre completo del lead. Se usa para dirigirse al contacto en los mensajes generados por IA y en los escritos por personas.
</ParamField>

<ParamField body="phone" type="string" required>
  Número de teléfono del lead en [formato E.164](https://en.wikipedia.org/wiki/E.164), p. ej. `+5491155551234`. Debe incluir el código de país.
</ParamField>

<ParamField body="email" type="string">
  Dirección de email del lead. Opcional: se omite si no está disponible.
</ParamField>

<ParamField body="channel" type="string" default="api">
  Canal de origen a asociar con este lead. Valores aceptados: `whatsapp`, `facebook`, `instagram`, `mercadolibre`, `web_form`, `email`, `phone`. Si no se indica, toma el valor `api`, lo que facilita identificar en los reportes los registros creados por código.
</ParamField>

<ParamField body="vehicle_interest" type="string">
  Descripción en texto libre del vehículo que le interesa al lead, p. ej. `"Toyota Hilux SRX 2024"`. El agente de IA usa este campo para personalizar las respuestas.
</ParamField>

<ParamField body="notes" type="string">
  Notas internas sobre este lead. Son visibles para el equipo en el Inbox unificado, pero nunca se envían al lead.
</ParamField>

## Ejemplo de solicitud

```bash cURL theme={null}
curl -X POST https://platform-api.deltalead.ai/v1/leads \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "María García",
    "phone": "+5491155551234",
    "email": "maria@example.com",
    "channel": "web_form",
    "vehicle_interest": "Toyota Hilux SRX 2024"
  }'
```

## Respuesta

Una solicitud exitosa devuelve HTTP `201 Created` con el objeto lead recién creado.

```json 201 Created theme={null}
{
  "id": "lead_abc123",
  "name": "María García",
  "phone": "+5491155551234",
  "email": "maria@example.com",
  "channel": "web_form",
  "vehicle_interest": "Toyota Hilux SRX 2024",
  "score": 0,
  "intent": "unknown",
  "status": "new",
  "assigned_to": null,
  "created_at": "2024-03-12T10:15:00Z",
  "updated_at": "2024-03-12T10:15:00Z",
  "last_activity_at": "2024-03-12T10:15:00Z",
  "organization_id": "org_00112233"
}
```

<Note>
  Crear un lead por la API **no** inicia automáticamente una conversación con IA. El `score` inicial del lead es `0` y su `intent` es `unknown` hasta que un agente de IA interactúe con el contacto. Para disparar una secuencia de contacto automatizada —como un saludo por WhatsApp o una llamada de seguimiento— hay que configurar un **workflow** en el panel de DeltaLead, en **Automatizaciones → Workflows**, y definir el disparador *"Lead creado por API"*.
</Note>