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

# API de Leads

> Referencia completa de la API de Leads de SalesOS: endpoints, parámetros y ejemplos.

# API de Leads

Endpoints para crear, consultar, actualizar y eliminar leads en SalesOS.

## Endpoints

### Listar leads

```bash theme={null}
GET /v1/leads
```

**Parámetros de consulta:**

| Parámetro        | Tipo   | Descripción                                            |
| ---------------- | ------ | ------------------------------------------------------ |
| `page`           | number | Número de página (default: 1)                          |
| `per_page`       | number | Registros por página (default: 20, max: 100)           |
| `search`         | string | Búsqueda por nombre, email o teléfono                  |
| `stage`          | string | Filtrar por etapa del pipeline                         |
| `assigned_to`    | string | Filtrar por vendedor asignado                          |
| `created_after`  | string | Filtrar leads creados después de esta fecha (ISO 8601) |
| `created_before` | string | Filtrar leads creados antes de esta fecha (ISO 8601)   |

**Ejemplo de solicitud:**

```bash theme={null}
curl -H "Authorization: Bearer TU_TOKEN" \
  "https://api.play2sell.com/v1/leads?page=1&per_page=20&stage=prospecting"
```

**Ejemplo de respuesta:**

```json theme={null}
{
  "data": [
    {
      "id": "lead_abc123",
      "name": "Juan Pérez",
      "email": "juan@empresa.com",
      "phone": "+52 55 1234 5678",
      "company": "Empresa SA",
      "stage": "prospecting",
      "assigned_to": "user_xyz789",
      "score": 75,
      "created_at": "2026-03-01T10:00:00Z",
      "updated_at": "2026-03-10T15:30:00Z"
    }
  ],
  "pagination": {
    "total": 150,
    "page": 1,
    "per_page": 20,
    "total_pages": 8
  }
}
```

### Obtener un lead

```bash theme={null}
GET /v1/leads/:id
```

### Crear un lead

```bash theme={null}
POST /v1/leads
```

**Cuerpo de la solicitud:**

```json theme={null}
{
  "name": "María García",
  "email": "maria@empresa.com",
  "phone": "+52 55 9876 5432",
  "company": "Tech Corp",
  "stage": "prospecting",
  "source": "website",
  "custom_fields": {
    "sector": "tecnología",
    "employees": 50
  }
}
```

**Campos requeridos:** `name`, `email`

### Actualizar un lead

```bash theme={null}
PATCH /v1/leads/:id
```

Envía solo los campos que deseas actualizar:

```json theme={null}
{
  "stage": "proposal",
  "score": 85
}
```

### Eliminar un lead

```bash theme={null}
DELETE /v1/leads/:id
```

<Warning>
  La eliminación de un lead es permanente y no se puede deshacer. Todos los datos asociados (notas, actividades, historial) también serán eliminados.
</Warning>

## Webhooks relacionados

Para recibir notificaciones cuando ocurren cambios en los leads, configura [webhooks](/es/api/endpoints/webhooks) para los siguientes eventos:

* `lead.created` — Nuevo lead creado
* `lead.updated` — Lead actualizado
* `lead.deleted` — Lead eliminado
* `lead.stage_changed` — Lead cambió de etapa

<Note>
  Todos los endpoints requieren autenticación. Consulta la guía de [autenticación](/es/api/authentication) para obtener tu token de acceso.
</Note>

## Próximos pasos

<CardGroup cols={2}>
  <Card title="API de Ventas" icon="handshake" href="/es/api/endpoints/sales">
    Gestiona oportunidades vía API.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/es/api/endpoints/webhooks">
    Recibe eventos en tiempo real.
  </Card>
</CardGroup>