# Listas

> Crear, gestionar y poblar listas de contactos

Source: https://docs.graph8.com/es/developers/lists/

> **Tip: ¿Usa la CLI?**
> La [CLI](https://docs.graph8.com/developers/cli/#g8-create-list) admite `g8 create-list`, `g8 add-to-list` y `g8 build-list` (búsqueda y guardado en un solo paso).

Las listas organizan contactos en grupos para campañas, exportaciones y segmentación.

Las listas también son el mecanismo mediante el cual los datos pasan del índice de datos abiertos a su espacio de trabajo. Al invocar [`/search/contacts/save`](https://docs.graph8.com/developers/search/#save-contacts-to-list) o [`/search/companies/save`](https://docs.graph8.com/developers/search/#save-companies-to-list), graph8 crea una nueva lista y la puebla con los registros coincidentes. Esos contactos y empresas pasan entonces a formar parte de sus datos propios, accesibles a través de los endpoints [`/contacts`](https://docs.graph8.com/developers/contacts/) y [`/companies`](https://docs.graph8.com/developers/companies/).

---

## Listar todas las listas

`GET /lists`

Devuelve un listado paginado de todas las listas de su organización.

### Parámetros de consulta

| Parámetro | Tipo | Predeterminado | Descripción |
|-----------|------|----------------|-------------|
| `page` | integer | `1` | Número de página (indexado desde 1) |
| `limit` | integer | `50` | Elementos por página (1-200) |

### Ejemplo

**cURL**

```bash
curl "https://be.graph8.com/api/v1/lists?limit=20" \
  -H "Authorization: Bearer $API_KEY"
```

**Python**

```python
response = requests.get(
    f"{BASE_URL}/lists",
    headers=HEADERS,
    params={"limit": 20}
)
lists = response.json()
```

**TypeScript**

```typescript
const response = await fetch(`${BASE_URL}/lists?limit=20`, {
  headers: { Authorization: `Bearer ${API_KEY}` }
});
const lists = await response.json();
```

### Respuesta

```json
{
  "data": [
    {
      "id": 10,
      "title": "Enterprise Prospects Q1",
      "type": "contacts",
      "source": "graph8",
      "status": "completed",
      "total": 1250,
      "is_dynamic": false,
      "tags": ["enterprise", "q1-2026"],
      "created_at": "2026-01-15T10:00:00Z",
      "created_by": "user_abc123",
      "updated_at": "2026-02-20T14:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 8,
    "has_next": false
  }
}
```

---

## Crear lista

`POST /lists`

Crea una nueva lista vacía. Agregue contactos después mediante el endpoint [Agregar contactos](#add-contacts-to-list).

### Cuerpo de la solicitud

| Campo | Tipo | Requerido | Predeterminado | Descripción |
|-------|------|-----------|----------------|-------------|
| `title` | string | Sí | — | Nombre de la lista |
| `type` | string | No | `"contacts"` | Tipo de lista: `contacts`, `companies`, `suppressions`, `deals`, `leads` |

### Ejemplo

**cURL**

```bash
curl -X POST "https://be.graph8.com/api/v1/lists" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Enterprise Prospects Q1", "type": "contacts"}'
```

**Python**

```python
response = requests.post(
    f"{BASE_URL}/lists",
    headers=HEADERS,
    json={"title": "Enterprise Prospects Q1", "type": "contacts"}
)
new_list = response.json()["data"]
```

**TypeScript**

```typescript
const response = await fetch(`${BASE_URL}/lists`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ title: "Enterprise Prospects Q1", type: "contacts" })
});
const { data: newList } = await response.json();
```

### Respuesta `201 Created`

```json
{
  "data": {
    "id": 11,
    "title": "Enterprise Prospects Q1",
    "type": "contacts",
    "status": "completed",
    "total": 0
  }
}
```

### Errores

| Estado | Significado |
|--------|-------------|
| `400` | Tipo de lista no válido |

---

## Eliminar lista

`DELETE /lists/{list_id}`

Eliminación lógica de una lista. La lista se marca como eliminada, pero no se borra de forma permanente.

Requiere el alcance `lists:delete`. Las claves de API de organización existentes que no tienen alcances siguen funcionando. Una clave de API que tiene alcances debe incluir `lists:delete`. Una clave de API personal actúa con el rol de su propietario, por lo que el propietario debe poder eliminar listas en graph8 y editar esta lista.

### Parámetros de ruta

| Parámetro | Tipo | Descripción |
|-----------|------|-------------|
| `list_id` | integer | ID de la lista |

### Ejemplo

**cURL**

```bash
curl -X DELETE "https://be.graph8.com/api/v1/lists/10" \
  -H "Authorization: Bearer $API_KEY"
```

**Python**

```python
response = requests.delete(f"{BASE_URL}/lists/10", headers=HEADERS)
```

**TypeScript**

```typescript
const response = await fetch(`${BASE_URL}/lists/10`, {
  method: "DELETE",
  headers: { Authorization: `Bearer ${API_KEY}` }
});
```

### Respuesta

```json
{
  "data": {
    "deleted": true
  }
}
```

### Errores

| Estado | Significado |
|--------|-------------|
| `403` | La clave tiene alcances pero no `lists:delete`, o el propietario de la clave personal no puede eliminar listas o no puede editar esta lista |
| `404` | Lista no encontrada |

> **Caution:**
> Eliminar una lista no elimina sus contactos. Los contactos permanecerán en su espacio de trabajo.

---

## Obtener contactos de una lista

`GET /lists/{list_id}/contacts`

Devuelve los contactos de una lista específica.

### Parámetros de ruta

| Parámetro | Tipo | Descripción |
|-----------|------|-------------|
| `list_id` | integer | ID de la lista |

### Parámetros de consulta

| Parámetro | Tipo | Predeterminado | Descripción |
|-----------|------|----------------|-------------|
| `page` | integer | `1` | Número de página (indexado desde 1) |
| `limit` | integer | `50` | Elementos por página (1-200) |

### Ejemplo

**cURL**

```bash
curl "https://be.graph8.com/api/v1/lists/10/contacts?limit=25" \
  -H "Authorization: Bearer $API_KEY"
```

**Python**

```python
response = requests.get(
    f"{BASE_URL}/lists/10/contacts",
    headers=HEADERS,
    params={"limit": 25}
)
contacts = response.json()["data"]
```

**TypeScript**

```typescript
const response = await fetch(`${BASE_URL}/lists/10/contacts?limit=25`, {
  headers: { Authorization: `Bearer ${API_KEY}` }
});
const { data: contacts } = await response.json();
```

### Respuesta

```json
{
  "data": [
    {
      "id": 1,
      "first_name": "Jane",
      "last_name": "Smith",
      "full_name": "Jane Smith",
      "work_email": "jane@acme.com",
      "job_title": "VP of Engineering",
      "seniority_level": "VP",
      "direct_phone": "+1-555-0100",
      "linkedin_url": "https://linkedin.com/in/janesmith",
      "city": "San Francisco",
      "state": "CA",
      "country": "US"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 1250,
    "has_next": true
  }
}
```

---

## Agregar contactos a una lista

`POST /lists/{list_id}/contacts`

Agrega uno o más contactos a una lista mediante sus IDs.

### Parámetros de ruta

| Parámetro | Tipo | Descripción |
|-----------|------|-------------|
| `list_id` | integer | ID de la lista |

### Cuerpo de la solicitud

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| `contact_ids` | integer[] | Sí | IDs de los contactos a agregar |

### Ejemplo

**cURL**

```bash
curl -X POST "https://be.graph8.com/api/v1/lists/10/contacts" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contact_ids": [1, 2, 3, 4, 5]}'
```

**Python**

```python
response = requests.post(
    f"{BASE_URL}/lists/10/contacts",
    headers=HEADERS,
    json={"contact_ids": [1, 2, 3, 4, 5]}
)
result = response.json()["data"]
```

**TypeScript**

```typescript
const response = await fetch(`${BASE_URL}/lists/10/contacts`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ contact_ids: [1, 2, 3, 4, 5] })
});
const { data: result } = await response.json();
```

### Respuesta `201 Created`

```json
{
  "data": {
    "added": 5
  }
}
```

---

## Eliminar contactos de una lista

`DELETE /lists/{list_id}/contacts`

Elimina uno o más contactos de una lista. Los contactos no se borran; únicamente se quitan de esta lista.

### Parámetros de ruta

| Parámetro | Tipo | Descripción |
|-----------|------|-------------|
| `list_id` | integer | ID de la lista |

### Cuerpo de la solicitud

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| `contact_ids` | integer[] | Sí | IDs de los contactos a eliminar |

### Ejemplo

**cURL**

```bash
curl -X DELETE "https://be.graph8.com/api/v1/lists/10/contacts" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contact_ids": [3, 4]}'
```

**Python**

```python
response = requests.delete(
    f"{BASE_URL}/lists/10/contacts",
    headers=HEADERS,
    json={"contact_ids": [3, 4]}
)
result = response.json()["data"]
```

**TypeScript**

```typescript
const response = await fetch(`${BASE_URL}/lists/10/contacts`, {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ contact_ids: [3, 4] })
});
const { data: result } = await response.json();
```

### Respuesta

```json
{
  "data": {
    "removed": 2
  }
}
```

> **Tip:**
> Para mover contactos entre listas, agréguelos primero a la lista de destino y luego quítelos de la lista de origen.