Consultar las importaciones de una lista

GET/v1/lists/{id}/imports

Para desarrolladores

Descripción

El historial de importaciones de una lista, 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

Path params:

idintegerobligatorio

Identificador de la lista.

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 importación.

list_idintegersiempre presente

Lista a la que pertenece.

job_idstring (UUID) | null

Trabajo que ejecuta la importación; su estado se consulta en GET /v1/jobs/{id}. null mientras la lista no declara sus columnas.

statusstring, enum: `awaiting_mapping | pending | processing | completed | failed`siempre presente

awaiting_mapping mientras la lista no declara sus columnas, pending mientras espera su turno, processing mientras se lee el archivo, y completed o failed al terminar.

file_namestring | null

Nombre que tenía el archivo al subirlo.

file_bytesinteger | null

Tamaño del archivo tal como se subió, en bytes.

encodingstring | null

Codificación del archivo: la detectada en sus primeras líneas hasta que se procesa, y después la que se decidió sobre el archivo completo (utf-8, utf-16, utf-32, cp1252).

delimiterstring | null

Separador de columnas: el indicado al subirlo o el detectado.

csv_row_countinteger | null

Filas leídas del archivo, sin contar la cabecera ni las filas en blanco. En una combinación, las leídas de las listas; en una instantánea, las del dataset. null hasta que se procesa.

imported_row_countinteger | null

Filas que quedaron en la lista. 0 si la importación falló.

failed_row_countinteger | null

Filas descartadas por un valor inválido, un campo obligatorio vacío, columnas de más o caracteres que no corresponden a la codificación.

duplicated_row_countinteger | null

Filas descartadas por repetir el valor de una columna única. En una combinación, las de un contacto que ya estaba en una lista anterior; en una instantánea, las filas más antiguas de un contacto que el dataset tiene repetido.

has_rejectsbooleansiempre presente

Si hay un archivo con las filas descartadas para descargar (GET /v1/lists/{id}/imports/{import_id}/rejects).

error_messagestring | null

Por qué falló la importación, si falló (en inglés).

diagnosticsobject | null

Detalle de la importación, descrito abajo.

encoding, format

La codificación con que se leyó el archivo y su formato: plain, gzip, zip o 7z. No están en una combinación ni en una instantánea.

source

En una instantánea: dataset_id, el dataset leído, y snapshot_at, el momento en que se leyó (UTC).

reasons

Filas descartadas por motivo. Cada fila cuenta una vez, con el primer motivo que encontró: invalid_character, extra_columns, required_missing, invalid_value o duplicated.

fields

Por field_key, cuántas filas tenían ese campo vacío siendo obligatorio, inválido o repetido. Una fila con dos campos inválidos cuenta en los dos.

repaired_rows / damaged_text_rows

Filas con texto dañado por una conversión de codificación anterior (José): reparadas si la lista tiene repair_encoding, o detectadas y cargadas tal cual si no.

error

Si la importación falló: code, y field o line cuando el problema tiene un lugar en el archivo.

source_listsobject[] | null

En una combinación (POST /v1/lists/merge), las listas que se combinaron, en orden. Cada una trae list_id e import_id, que es la importación de la que salieron sus datos. null en una importación de archivo o en una instantánea.

identity_fieldstring | null

En una combinación o en una instantánea, el campo que identifica a un contacto: EMAIL, PHONE o UNIQUECODE. null en una importación de archivo.

collision_policystring | null

En una combinación, cómo se resolvió un contacto que estaba en varias listas: discard, fill, update o replace. null en una importación de archivo o en una instantánea.

delete_sourcesboolean | null

En una combinación, si las listas de origen se eliminan al terminar. null en una importación de archivo o en una instantánea.

created_atstring (date-time)siempre presente

Cuándo se subió el archivo (ISO 8601, UTC).

started_atstring (date-time) | null

Cuándo empezó a leerse.

finished_atstring (date-time) | null

Cuándo terminó, haya completado o fallado.

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/imports" \
-H "Authorization: Bearer $API_KEY" \
-H "X-Instance-Slug: $SLUG"

Response

{
"data": [
  {
    "id": 17,
    "list_id": 4,
    "job_id": "01a13a48-9e05-7d41-9a8f-3c1d2e4f5a6b",
    "status": "pending",
    "file_name": "clientes-marzo.csv",
    "file_bytes": 182344,
    "encoding": "cp1252",
    "delimiter": ";",
    "csv_row_count": null,
    "imported_row_count": null,
    "failed_row_count": null,
    "duplicated_row_count": null,
    "has_rejects": false,
    "error_message": null,
    "diagnostics": null,
    "source_lists": null,
    "identity_field": null,
    "collision_policy": null,
    "delete_sources": null,
    "created_at": "2026-10-14T12:00:00Z",
    "started_at": null,
    "finished_at": null
  }
],
"pagination": {
  "page": 1,
  "page_size": 20,
  "has_more": false,
  "total_items": 1,
  "total_pages": 1
}
}