Actualizar una lista de contactos

PATCH/v1/lists/{id}

Para desarrolladores

Descripción

Cambia el nombre, los canales o la descripción de una lista. Solo cambian los campos que se envían.

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:

{
  "name": "Clientes abril",
  "description": null
}

namestring

Mismas reglas que al crear. No admite null.

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

null deja la lista sin canales.

descriptionstring | null

null borra la descripción.

repair_encodingboolean

Si la importación repara el texto dañado por una conversión de codificación anterior (ver POST /v1/lists). No admite null, y solo se puede cambiar mientras la lista no tiene datos ni una importación en curso.

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

Response

200 OKDevuelve un objeto con los campos que siguen.

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
404	La lista no existe o fue eliminada (list_not_found).
409	Ya existe otra lista vigente con el nombre nuevo (list_name_taken). También cuando se cambia repair_encoding en una lista que salió de una instantánea (list_is_snapshot), que ya tiene datos (list_has_data) o que tiene una importación en curso (list_import_in_progress).
422	El body no es válido, o name o repair_encoding vienen en null.

Request

curl -X PATCH "https://$API_HOST/v1/lists/12" \
-H "Authorization: Bearer $API_KEY" \
-H "X-Instance-Slug: $SLUG" \
-H "Content-Type: application/json" \
-d '{
  "name": "Clientes abril",
  "description": null
}'

Response

{
"id": 4,
"name": "Clientes marzo",
"channel": [
  "mail"
],
"description": null,
"row_count": 0,
"repair_encoding": false,
"source_dataset_id": null,
"origin": "file",
"copied_to_datasets": 1,
"last_import": {
  "id": 7,
  "status": "completed",
  "job_id": "01934a3c-7b2e-7e10-8a3c-5d2f1b9c4e00",
  "has_rejects": true,
  "file_name": "clientes-marzo.csv",
  "source_list_count": null,
  "collision_policy": null
},
"created_at": "2026-10-14T12:00:00Z",
"updated_at": "2026-10-14T12:00:00Z"
}