Listas

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 o /search/companies/save, 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 y /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 "https://be.graph8.com/api/v1/lists?limit=20" \
  -H "Authorization: Bearer $API_KEY"

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

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

Respuesta

{
  "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.

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 -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"}'

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

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`

{
  "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.

Parámetros de ruta

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

Ejemplo

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

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

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

Respuesta

{
  "data": {
    "deleted": true
  }
}

Errores

Estado	Significado
`404`	Lista no encontrada

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 "https://be.graph8.com/api/v1/lists/10/contacts?limit=25" \
  -H "Authorization: Bearer $API_KEY"

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

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

Respuesta

{
  "data": [
    {
      "id": 1,
      "first_name": "Jane",
      "last_name": "Smith",
      "full_name": "Jane Smith",
      "work_email": "[email protected]",
      "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 -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]}'

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

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`

{
  "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 -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]}'

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

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

{
  "data": {
    "removed": 2
  }
}

Listas

Listar todas las listas

Parámetros de consulta

Ejemplo

Respuesta

Crear lista

Cuerpo de la solicitud

Ejemplo

Respuesta 201 Created

Errores

Eliminar lista

Parámetros de ruta

Ejemplo

Respuesta

Errores

Obtener contactos de una lista

Parámetros de ruta

Parámetros de consulta

Ejemplo

Respuesta

Agregar contactos a una lista

Parámetros de ruta

Cuerpo de la solicitud

Ejemplo

Respuesta 201 Created

Eliminar contactos de una lista

Parámetros de ruta

Cuerpo de la solicitud

Ejemplo

Respuesta

Respuesta `201 Created`

Respuesta `201 Created`