Crear una lista de contactos

POST/v1/lists

Para desarrolladores

Descripción

Crea una lista. La lista nace sin columnas: declare a qué campo del catálogo corresponde cada columna del CSV con PUT /v1/lists/{id}/fields. Puede declararlas antes de subir el archivo, o después, a partir de la propuesta de 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

Body:

{
  "name": "Clientes marzo",
  "channel": ["mail"],
  "description": "Exportación mensual del CRM"
}

namestringobligatorio

1–255 caracteres, sin contar los espacios de los extremos, que se quitan. Único entre las listas vigentes, sin distinguir mayúsculas ni tildes.

channelstring[], enum: `mail | sms | wsp` | null

Vías por las que se le puede hablar a los contactos de la lista.

descriptionstring | null

Descripción libre.

repair_encodingboolean

Si la importación repara el texto que llega dañado por una conversión de codificación anterior: José pasa a José. Default: false; sin la opción, ese texto se carga tal cual y la importación lo cuenta en diagnostics.damaged_text_rows.

Un campo que no figura en esta tabla se rechaza con 422.

Response

201 CreatedDevuelve el objeto creado. El header Location trae su URL (ver Headers).

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
409	Ya existe una lista vigente con ese nombre (list_name_taken).
422	El body no es válido.

Detalle completo en Errores genéricos.

Notas

• El nombre de una lista eliminada queda libre para una lista nueva.

Request

curl -X POST "https://$API_HOST/v1/lists" \
-H "Authorization: Bearer $API_KEY" \
-H "X-Instance-Slug: $SLUG" \
-H "Content-Type: application/json" \
-d '{
  "name": "Clientes marzo",
  "channel": [
    "mail"
  ]
}'

Response

{
"id": 4,
"name": "Clientes marzo",
"channel": [
  "mail"
],
"description": "Exportación mensual del CRM",
"row_count": 0,
"repair_encoding": false,
"source_dataset_id": null,
"origin": null,
"copied_to_datasets": 0,
"last_import": null,
"created_at": "2026-10-14T12:00:00Z",
"updated_at": "2026-10-14T12:00:00Z"
}