API para integradores Referencia

API de Marketing: añadir o actualizar un contacto en una lista

Referencia del punto de API que mete un contacto en una lista de Marketing desde otra aplicación, con su autenticación y sus respuestas.

Actualizado el 30 de octubre de 2026

Esta función tiene un fallo conocido que todavía no está resuelto.

En esta página

Para qué sirve
Quién puede usarlo
La clave
La lista
La llamada
Qué pasa con el contacto
Las respuestas
Lo que conviene saber
Errores frecuentes

En resumen

Envía cada contacto con POST a https://app.affiliatracker.com/api/marketing/contacts/sync, de servidor a servidor.
Autentícate con la clave API de Marketing de tu cuenta: Authorization: Bearer <clave>.
El cuerpo es JSON con id_list y email (obligatorios), y name y custom_fields (opcionales).
Si el correo ya está en esa lista, se sustituyen su nombre y sus datos extra por los que mandes: manda siempre todos.
Quien se dio de baja sigue de baja. Fíate del código HTTP 200, no sólo del JSON.

Para qué sirve

Es la referencia para quien conecta otra aplicación (el formulario de una web, una tienda, un CRM externo) con las listas de Marketing Cloud: cada llamada mete un contacto en una lista, o lo actualiza si ya estaba. Si esa lista dispara una automatización, se pone en marcha en ese momento (Workflows: automatizaciones visuales de Marketing).

Quién puede usarlo

No hay usuarios ni permisos: quien tenga la clave API de Marketing de la cuenta puede llamar, y la clave decide en qué cuenta entra el contacto. Para ver o renovar la clave hace falta, en el panel de permisos, el interruptor de Configuración (Settings) encendido y Acceso Total en su fila SMTP & API Keys.

La clave

Está en el engranaje › Configuración, grupo Marketing Cloud › SMTP & API Keys, pestaña Claves API y Webhooks. En la fila Master Key (Integraciones) ① sale tapada; el ojo ② la enseña y el otro botón ③ la copia. Empieza por mkt_live_.

Hay una sola clave por cuenta.
Generar nueva clave API ④ crea otra y la anterior deja de valer en ese momento: cualquier integración que la use deja de meter contactos hasta que la cambies. La pantalla lo avisa antes.
Más sobre esta pantalla: SMTP y API: credenciales de Amazon SES y clave API de Marketing.

La lista

id_list es el número de la lista: lo ves junto a su nombre al abrirla en Listas (CSV / API) (ID: 3, por ejemplo ①). La lista tiene que existir: la API no crea listas (Listas de contactos: crear, ver, filtrar y añadir contactos).

La llamada

POST https://app.affiliatracker.com/api/marketing/contacts/sync
Content-Type: application/json
Authorization: Bearer <clave>

Sólo POST, de servidor a servidor: en una página web la clave quedaría a la vista.
Escribe Bearer con la B mayúscula y un espacio detrás: con bearer la clave no se reconoce.

El cuerpo

Campo	Obligatorio	Qué es
`id_list`	Sí	El número de la lista.
`email`	Sí	El correo. Se guarda en minúsculas y sin espacios alrededor. No se comprueba su formato: valídalo antes de enviar.
`name`	No	El nombre.
`custom_fields`	No	Un objeto con los datos extra (`{"provincia": "Madrid"}`). Se guarda entero.

Las claves de custom_fields que coinciden con un campo personalizado de la cuenta salen después en los filtros de la lista, en sus segmentos y en Añadir Contacto. Las demás se guardan igual, pero no salen en esas pantallas (Campos personalizados de los contactos).

Ejemplo

curl -X POST "https://app.affiliatracker.com/api/marketing/contacts/sync" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TU_CLAVE" \
  -d '{"id_list": 3, "email": "ana.martin@ejemplo.test", "name": "Ana Martín", "custom_fields": {"provincia": "Madrid", "sector": "Restauración"}}'

Qué pasa con el contacto

Si no estaba en esa lista, se crea.
Si ya estaba (el mismo correo, sin distinguir mayúsculas ni acentos), se sustituyen su nombre y sus datos extra por los de la llamada. Si no mandas custom_fields, sus datos extra se quedan vacíos; si no mandas name, el nombre también. Manda siempre todo lo que quieras conservar.
Si se dio de baja de tu empresa, sigue de baja: la API nunca devuelve los correos a nadie, y si la dirección está en la lista de bajas de la cuenta, entra ya marcada (Bajas: cómo se da de baja un contacto y a quién afecta).
Se ponen en marcha las automatizaciones activas que empiezan con esa lista (Workflows: automatizaciones visuales de Marketing).

Las respuestas

Cuándo	HTTP	Cuerpo
Se ha guardado	200	`{"success":true,"message":"Contacto guardado y flujos evaluados","id_account":999990,"workflow_log":null}`
Falta `id_list` o `email`, o el cuerpo no es JSON	400	`{"error":"id_list y email son obligatorios"}`
Falta la clave, no es la de ninguna cuenta o la cabecera está mal escrita	401	`{"error":"No autorizado. API Key inv\u00e1lida."}`
La lista no existe o no es de tu cuenta	403	`{"error":"La lista especificada no pertenece a esta cuenta."}`
Fallo del servidor	500	`{"error":"…"}`

id_account es el número de tu cuenta. workflow_log llega siempre a null.
Si la lista pone en marcha una automatización, la respuesta puede llegar con texto añadido delante del JSON, aunque el contacto se haya guardado. Da por bueno el código 200 aunque el cuerpo no se pueda leer como JSON.
Las tildes llegan escapadas en el JSON (\u00e1 en vez de «á»): léelo con un decodificador JSON.

Lo que conviene saber

No hay entorno de pruebas: cada llamada con la clave buena escribe en la lista real. Para probar, crea una lista aparte y mete en ella un correo de prueba.
Sólo añade y actualiza: no borra contactos, no los mueve de lista y no devuelve el contacto guardado.
Lo que llega por la API no se distingue en la pantalla: el Origen de la lista dice Archivo CSV / Manual igual.

Errores frecuentes

Lo que ves	Qué significa	Qué hacer
`{"error":"No autorizado. API Key inv\u00e1lida."}`	La clave no llega, ya no vale, o la cabecera dice `bearer` en minúscula.	Copia la clave actual y escribe `Authorization: Bearer <clave>`.
`{"error":"id_list y email son obligatorios"}`	Falta uno de los dos, o el cuerpo no es JSON válido.	Revisa el cuerpo y el `Content-Type: application/json`.
`{"error":"La lista especificada no pertenece a esta cuenta."}`	Ese número no es de una lista de tu cuenta.	Copia el número que sale junto al nombre de la lista al abrirla (ID: 3, por ejemplo).
El contacto ha perdido sus datos extra	Se ha reenviado sin `custom_fields`.	Manda siempre todos los datos extra.
La respuesta no se puede leer como JSON	La lista ha puesto en marcha una automatización.	Mira el código HTTP: 200 es que se ha guardado.
Un contacto de la lista no recibe las campañas	Se dio de baja, o su correo no es válido.	Revisa el correo; si se dio de baja, sólo soporte lo puede cambiar.