Obtener una lista de contactos

GET/v1/lists/{id}

Para desarrolladores

Descripción

Devuelve una lista por su identificador.

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

Path params:

idintegerobligatorio

Identificador de la lista.

Response

200 OKDevuelve un objeto con 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.

Errores

Código	Cuándo
404	La lista no existe o fue eliminada (list_not_found).

Request

curl -X GET "https://$API_HOST/v1/lists/12" \
-H "Authorization: Bearer $API_KEY" \
-H "X-Instance-Slug: $SLUG"

Response

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