Saltar al contenido principal

Exportar una lista de contactos a CSV

POST/v1/lists/{id}/export

Para desarrolladores

Descripción​

Exporta los datos de una lista a un archivo CSV. La exportación es un trabajo en segundo plano: la respuesta llega antes de que se escriba el archivo, y el trabajo se sigue en la URL del header Location (GET /v1/jobs/{id}). Cuando termina, el archivo se descarga con GET /v1/jobs/{id}/file hasta la fecha de result.expires_at.

Si la lista ya tiene una exportación en curso, o terminada y sin vencer, la respuesta es esa exportación y no se crea otra: los datos de una lista no cambian una vez cargados.

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.

No lleva body.

Response​

201 CreatedDevuelve el objeto creado. El header Location trae su URL (ver Headers).
idstring (UUID)siempre presente
Identificador del trabajo.
typestring, enum: `list_import | list_merge | list_snapshot | list_export | list_copy`siempre presente
Qué hace el trabajo: list_import importa un archivo en una lista, list_merge combina listas en una nueva, list_snapshot toma la instantánea de un dataset en una lista nueva, list_export exporta los datos de una lista a un CSV y list_copy copia los contactos de una lista a un dataset.
statusstring, enum: `pending | processing | completed | failed`siempre presente
pending mientras espera su turno, processing mientras se ejecuta, y completed o failed al terminar.
paramsobjectsiempre presente
Sobre qué trabaja. En los trabajos de listas, list_id e import_id: la lista que recibe los datos y su importación. En list_copy, list_id e import_id son la lista de origen y su importación, y se suman dataset_id (el dataset de destino) y rate_per_minute, el máximo de contactos por minuto de la copia: la tasa que tenía el dataset al pedirla, compartida con la API.
resultobject | null
El resultado del trabajo, según su tipo (type). En list_export, el archivo: row_count (filas), size_bytes (tamaño en bytes), expires_at (hasta cuándo se puede descargar) y, una vez borrado, purged_at. En list_copy, los conteos de la copia (ver Copiar una lista a un dataset). Mientras la copia se ejecuta, muestra lo enviado hasta ese momento y next_row, la primera fila que falta enviar. En list_import, list_merge y list_snapshot es null: el resultado está en su importación (import_id de params).
error_codestring | null
Código del error, si falló (ver Notas de GET /v1/jobs/{id}).
error_messagestring | null
Por qué falló, si falló (en inglés).
created_atstring (date-time)siempre presente
Cuándo se creó el trabajo (ISO 8601, UTC).
started_atstring (date-time) | null
Cuándo empezó su último intento.
finished_atstring (date-time) | null
Cuándo terminó, haya completado o fallado.
Notas
  • 200 OK, con el mismo header y el mismo body, cuando ya había una exportación de la lista en curso o sin vencer.
  • Mismos campos que GET /v1/jobs/{id}.
  • El trabajo nace en estado pending.

Errores​

CódigoCuándo
404La lista no existe o fue eliminada (list_not_found).
409La lista todavía no tiene datos (list_has_no_data).
503No se pudo dejar la exportación en cola (service_unavailable). No queda nada creado: reintente.

Detalle completo en Respuestas de error.

Notas
  • El archivo: CSV separado por comas, en UTF-8 con BOM, para que una planilla lo abra con los acentos correctos. La primera fila trae el nombre de cada campo, en el orden de las columnas de la lista, y después hay una fila por contacto.
  • Los valores se escriben como la importación los vuelve a leer: un número sin decimales de sobra ni notación científica, una fecha como YYYY-MM-DD, un sí/no como true/false, y las opciones de una selección múltiple en una sola celda, separadas por comas.
  • Una celda que empieza como una fórmula de planilla (=, +, -, @) se escribe con un apóstrofo delante, para que se abra como texto. Si el archivo se vuelve a importar, el apóstrofo se quita.
  • El archivo se puede descargar durante 24 horas desde que termina la exportación; después se borra y hay que pedir otra exportación.
  • Al terminar, result del trabajo trae row_count (las filas del archivo), size_bytes y expires_at.
Request
curl -X POST "https://$API_HOST/v1/lists/12/export" \
-H "Authorization: Bearer $API_KEY" \
-H "X-Instance-Slug: $SLUG"
Response
{
"id": "01a14d2e-7c31-7f02-9b6e-4d5c6b7a8e9f",
"type": "list_export",
"status": "pending",
"params": {
  "list_id": 12,
  "import_id": 31
},
"result": null,
"error_code": null,
"error_message": null,
"created_at": "2026-10-18T12:00:00Z",
"started_at": null,
"finished_at": null
}