Saltar al contenido principal

Consultar las listas de contactos

GET/v1/lists

Para desarrolladores

Descripción​

Una lista es un conjunto de contactos que recibe sus datos una sola vez: de un archivo CSV, de otras listas o de un dataset. Cada columna del archivo se declara como un campo del catálogo (PUT /v1/lists/{id}/fields). Para combinar otras listas, use POST /v1/lists/merge. Para una instantánea de un dataset, use POST /v1/datasets/{id}/snapshot. Una vez cargada no cambia: para cargar un archivo nuevo, cree una lista nueva. Si lo que se necesita es un registro que se actualiza con el tiempo desde varias fuentes, el recurso es un dataset (ver Campos, formularios y consentimiento).

Este endpoint lista las listas de la cuenta, de la más reciente a la más antigua.

Autenticación​

Authorizationbearer tokenheaderobligatorio
API key con scope list:read. Formato: Bearer <API_KEY>.
X-Instance-Slugstringheaderobligatorio
Identificador de su instancia. Ver Autenticación.

Request​

Query params:

pageinteger
Número de página; la primera es la 1. Default: 1.
page_sizeinteger
Tamaño de página, 1–100. Default: 20.

Response​

200 OKDevuelve una página de resultados: data con los elementos y pagination para pedir la siguiente. Cada elemento tiene los campos que siguen.
idintegersiempre presente
Identificador de la lista.
namestringsiempre presente
Nombre visible, único entre las listas vigentes.
channelstring[] | null
Vías por las que se le puede hablar a sus contactos: mail, sms, wsp.
descriptionstring | null
Descripción libre.
row_countintegersiempre presente
Filas de la lista. 0 mientras la lista no haya recibido sus datos.
repair_encodingbooleansiempre presente
Si la importación repara el texto dañado por una conversión de codificación anterior (José pasa a José).
source_dataset_idinteger | null
El dataset del que salió la lista por una instantánea. null en una lista de archivo o de combinación.
originstring | null
De dónde salieron sus datos: file (un archivo), merge (una combinación) o dataset (una instantánea). null mientras la lista no recibió nada.
copied_to_datasetsintegersiempre presente
En cuántos datasets distintos se copiaron los contactos de la lista. Solo cuentan las copias que terminaron.
last_importobject | null
La importación más reciente. Si la lista tiene datos, es la que se los dio. Si todavía no los tiene, es la que está en curso o la última que falló. null si la lista no tiene ninguna importación. Su detalle completo se lee en GET /v1/lists/{id}/imports/{import_id}.
idintegersiempre presente
Identificador de la importación.
statusstringsiempre presente
awaiting_mapping mientras la lista no declara sus columnas, pending mientras espera su turno, processing mientras se cargan los datos, y completed o failed al terminar.
job_idstring | null
Trabajo que ejecuta la importación, consultable en GET /v1/jobs/{id}. null mientras la lista no declara sus columnas.
has_rejectsbooleansiempre presente
Si la importación dejó filas descartadas, que se descargan con GET /v1/lists/{id}/imports/{import_id}/rejects.
file_namestring | null
Nombre del archivo subido. null en una combinación o una instantánea.
source_list_countinteger | null
Cuántas listas leyó una combinación. null en las demás.
collision_policystring | null
Cómo resolvió una combinación un contacto que está en varias listas: discard, fill, update o replace. null en las demás.
created_atstring (date-time)siempre presente
Fecha de creación (ISO 8601, UTC).
updated_atstring (date-time)siempre presente
Fecha de la última modificación de la lista.
Notas
Request
curl -X GET "https://$API_HOST/v1/lists" \
-H "Authorization: Bearer $API_KEY" \
-H "X-Instance-Slug: $SLUG"
Response
{
"data": [
  {
    "id": 4,
    "name": "Clientes marzo",
    "channel": [
      "mail"
    ],
    "description": null,
    "row_count": 0,
    "repair_encoding": false,
    "source_dataset_id": null,
    "origin": "file",
    "copied_to_datasets": 1,
    "last_import": {
      "id": 7,
      "status": "completed",
      "job_id": "01934a3c-7b2e-7e10-8a3c-5d2f1b9c4e00",
      "has_rejects": true,
      "file_name": "clientes-marzo.csv",
      "source_list_count": null,
      "collision_policy": null
    },
    "created_at": "2026-10-14T12:00:00Z",
    "updated_at": "2026-10-14T12:00:00Z"
  }
],
"pagination": {
  "page": 1,
  "page_size": 20,
  "has_more": false,
  "total_items": 1,
  "total_pages": 1
}
}