Importar un CSV a una lista
POST
/v1/lists/{id}/importsPara desarrolladores
Descripción
Sube un archivo CSV a una lista. La importación queda en cola y la respuesta llega antes de
que se lean sus filas: el estado se consulta después en la URL del header Location
(GET /v1/lists/{id}/imports/{import_id}).
Con append las filas del archivo se suman a las que la lista ya tiene; con overwrite las
reemplazan. Cada columna del archivo se interpreta según las columnas declaradas de la lista
(PUT /v1/lists/{id}/fields), por su posición.
Las primeras líneas del archivo quedan como vista previa de la lista
(GET /v1/lists/{id}/preview).
Autenticación
Authorizationbearer tokenheaderobligatorio- API key con scope
list:write. Formato:Bearer <API_KEY>. X-Instance-Slugstringheaderobligatorio- Identificador de su instancia. Ver Autenticación.
Request
Path params:
idintegerobligatorio- Identificador de la lista.
Body (multipart/form-data):
filefileobligatorio- El CSV. Hasta 50 MB (52 428 800 bytes).
modestring, enum: `append | overwrite`obligatorioappendsuma las filas a las de la lista;overwritelas reemplaza.
El archivo:
- Codificación: UTF-8 (con o sin BOM), UTF-16 con BOM, o Windows-1252, que es la que usa Excel en español al guardar como "CSV (delimitado por comas)". Se detecta sola.
- Separador: coma, punto y coma, tabulación o barra vertical (
|). Se detecta solo. - Un archivo de Excel (
.xlsx) no es un CSV, aunque se le cambie la extensión: hay que guardarlo como CSV desde Excel.
Response
201 CreatedDevuelve el objeto creado. El header
Location trae su URL (ver Headers).idintegersiempre presente- Identificador de la importación.
list_idintegersiempre presente- Lista a la que pertenece.
modestring, enum: `append | overwrite`siempre presente- Si el archivo se suma a la lista o la reemplaza.
statusstring, enum: `pending | processing | completed | failed`siempre presentependingmientras espera su turno,processingmientras se lee el archivo, ycompletedofailedal terminar.file_namestring | null- Nombre que tenía el archivo al subirlo.
file_bytesinteger | null- Tamaño del archivo, en bytes.
encodingstring | null- Codificación detectada en el archivo (
utf-8,utf-8-sig,utf-16,cp1252). delimiterstring | null- Separador de columnas detectado.
csv_row_countinteger | null- Filas leídas del archivo.
nullhasta que se procesa. imported_row_countinteger | null- Filas que quedaron en la lista.
failed_row_countinteger | null- Filas descartadas por un valor inválido o un campo obligatorio vacío.
duplicated_row_countinteger | null- Filas descartadas por repetir el valor de una columna única.
error_messagestring | null- Por qué falló la importación, si falló.
diagnosticsobject | null- Detalle de las filas descartadas y sus motivos.
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). |
| 409 | La lista no tiene columnas declaradas (list_has_no_fields); la lista superaría su tamaño máximo con este archivo (list_size_exceeded); o, en append, el mismo archivo ya está en la lista por una importación anterior o en curso (list_import_duplicated). |
| 413 | El archivo supera los 50 MB (request_too_large). |
| 422 | Falta file o mode, o mode no es válido. También con errors[].code propio en /file: el archivo está vacío (list_file_empty) o no es un archivo de texto (list_file_not_text). |
| 503 | No se pudo dejar la importación en cola (service_unavailable). No queda nada registrado: reintente. |
Detalle completo en Errores genéricos.
Notas
- Un archivo se compara por su contenido exacto. En
append, volver a subir un archivo idéntico a uno que ya está en la lista se rechaza (409), para no cargar las mismas filas dos veces. Un archivo de una importación que falló, o anterior a unoverwrite, ya no cuenta como cargado. Enoverwritela repetición no importa: el archivo reemplaza los datos de la lista. - El tamaño máximo de una lista se mide sobre los datos que ya tiene más el archivo
entrante. Para volver a cargar una lista desde cero, use
overwrite. - Las columnas se leen por posición: la primera columna del archivo es la que se declaró
con
csv_pos1.
Request
curl -X POST "https://$API_HOST/v1/lists/4/imports" \
-H "Authorization: Bearer $API_KEY" \
-H "X-Instance-Slug: $SLUG" \
-F "[email protected];type=text/csv" \
-F "mode=append"
Response
{
"id": 17,
"list_id": 4,
"mode": "append",
"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,
"error_message": null,
"diagnostics": null,
"created_at": "2026-10-14T12:00:00Z",
"started_at": null,
"finished_at": null
}