Obtener el estado de una importación

GET/v1/lists/{id}/imports/{import_id}

Para desarrolladores

Descripción

El estado de una importación: si terminó, cuántas filas quedaron en la lista y cuántas se descartaron, y por qué falló si falló. Es la URL que devuelve POST /v1/lists/{id}/imports en el header Location.

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.

import_idintegerobligatorio

Identificador de la importación.

Response

200 OKDevuelve un objeto con 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 (list_not_found), o la importación no existe o es de otra lista (list_import_not_found).

Notas

• Las filas leídas se reparten entre las importadas, las descartadas por un problema propio y las descartadas por repetidas: csv_row_count = imported_row_count + failed_row_count + duplicated_row_count.
• Para seguir una importación, consulte esta URL cada algunos segundos hasta que status sea completed o failed. El trabajo de job_id (GET /v1/jobs/{id}) lleva el mismo estado y las mismas fechas, sin los contadores de filas.
• Una importación en awaiting_mapping no avanza sola: queda en cola cuando se declaran las columnas de la lista (PUT /v1/lists/{id}/fields).
• Una fila con un problema se descarta y la importación sigue. La importación falla solo por un problema del archivo entero. En ese caso la lista queda sin datos y acepta el archivo corregido. Los casos son estos:

diagnostics.error.code	Cuándo
list_file_archive_empty, list_file_archive_multiple, list_file_archive_encrypted, list_file_archive_corrupt	El comprimido no trae exactamente un archivo, tiene contraseña o está dañado.
list_file_is_spreadsheet	El archivo es una planilla y no un CSV.
list_import_disk_full	El contenido, una vez descomprimido, es más grande de lo que una importación puede procesar.
list_file_has_no_rows	El archivo está vacío o solo tiene la cabecera.
list_file_columns_missing	Un campo declarado apunta a una columna que la cabecera no tiene.
list_file_malformed	Una comilla sin cerrar o mal ubicada; line dice en qué línea empieza el registro.
list_field_pattern_invalid	El patrón del campo field usa una construcción que la importación no admite (por ejemplo, referencias hacia atrás).
list_import_field_systematic	El campo field está vacío o es inválido en la mitad o más de las filas: suele ser una columna mapeada al campo equivocado o con otro formato, como fechas con el mes primero.
list_import_no_valid_rows	No quedó ninguna fila válida.
list_not_found, list_has_no_fields, list_has_data	La lista se eliminó, se quedó sin columnas o ya recibió sus datos mientras esperaba.
list_import_internal_error	No se pudo procesar por un error interno: vuelva a subir el archivo.
job_attempts_exhausted	La importación falló en cada intento sin un error propio. Suele deberse a un archivo que la plataforma no puede procesar por su tamaño: subirlo de nuevo falla igual: divídalo en archivos más pequeños.
list_import_superseded	Esperaba las columnas de la lista y se subió otro archivo, que la reemplazó. Su archivo se borra.
list_merge_source_missing	En una combinación, no se encontraron los datos de una lista de origen.
list_snapshot_dataset_missing	En una instantánea, el dataset se eliminó mientras esperaba su turno.
list_snapshot_too_large	En una instantánea, el dataset tiene más filas de las que admite una instantánea (15 millones de filas). csv_row_count dice cuántas tenía.

Cuando falla por list_import_field_systematic, el archivo de rechazos muestra las filas y su motivo, y suele bastar para ver qué columna está mal.

Una importación que la plataforma no termina en su plazo falla con job_expired. Ese código se ve en el trabajo (GET /v1/jobs/{id}) y no en diagnostics; la importación lo muestra en error_message. Vuelva a pedir la operación: subir el archivo, combinar las listas o tomar la instantánea.

Una lista que salió de una instantánea no acepta un archivo después de fallar: tome otra instantánea del dataset.

Request

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

Response

{
"id": 17,
"list_id": 4,
"job_id": "01a13a48-9e05-7d41-9a8f-3c1d2e4f5a6b",
"status": "completed",
"file_name": "clientes-marzo.csv.gz",
"file_bytes": 182344,
"encoding": "cp1252",
"delimiter": ";",
"csv_row_count": 2500,
"imported_row_count": 2480,
"failed_row_count": 15,
"duplicated_row_count": 5,
"has_rejects": true,
"error_message": null,
"diagnostics": {
  "encoding": "cp1252",
  "format": "gzip",
  "reasons": {
    "invalid_value": 12,
    "required_missing": 3,
    "duplicated": 5
  },
  "fields": {
    "EMAIL": {
      "invalid_value": 12,
      "duplicated": 5
    },
    "FIRST_NAME": {
      "required_missing": 3
    }
  },
  "damaged_text_rows": 0
},
"source_lists": null,
"identity_field": null,
"collision_policy": null,
"delete_sources": null,
"created_at": "2026-10-14T12:00:00Z",
"started_at": "2026-10-14T12:00:02Z",
"finished_at": "2026-10-14T12:00:09Z"
}