Crear una lista

POST/v1/lists

Para desarrolladores

Descripción

Crea una lista. La lista nace sin columnas: el paso siguiente es declarar a qué campo del catálogo corresponde cada columna del CSV, con PUT /v1/lists/{id}/fields.

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.

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 según la última importación completada. 0 mientras no se haya importado nada.

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,
"created_at": "2026-10-14T12:00:00Z",
"updated_at": "2026-10-14T12:00:00Z"
}