Audiencias

​

Audiencias personalizadas

​

Descripción general

Existen múltiples formas para que los socios creen Custom Audiences.

• Audience API (CRM)
• Web
• Mobile
• Flexible

Ten en cuenta que no puedes excluir las custom audiences lookalike de la segmentación. Además, no puedes segmentar simultáneamente una custom audience y su lookalike en el mismo elemento de línea de anuncio (grupo de anuncios).

Administración de audiencias

Las audiencias pueden administrarse a través de socios de audiencias y socios de la Ads API. Ofrecemos una serie de endpoints en la API para acceder y mantener custom audiences.

Para obtener información sobre custom audiences, ofrecemos 2 endpoints:

• GET accounts/:account_id/custom_audiences
• GET accounts/:account_id/custom_audiences/:custom_audience_id

Para más detalles sobre cómo cargar y administrar audiencias, consulta la guía de la Audience API.

Tiempos de procesamiento

En términos generales, los cambios en las audiencias se procesan en lotes que se ejecutan cada 6 a 8 horas. Mientras se procesa un cambio de audiencia, la audiencia existente que se va a actualizar no se ve afectada. No recomendamos realizar más de una actualización para altas y una actualización para bajas por audiencia dentro de este período.

Segmentación

Una audiencia solo puede segmentarse si coincide con al menos 100 usuarios activos en los últimos 90 días en clientes propiedad y operados por X. GET accounts/:account_id/custom_audiences/:custom_audience_id indicará si una audiencia no puede segmentarse porque coincide con muy pocos usuarios.

Audience API (CRM)

Los socios de audiencia o de API proporcionan una lista de identificadores con hash y X realiza la correspondencia y genera segmentos que se ponen a disposición para la compra de medios en X. Los socios pueden crear estas audiencias con la Audience API.

¿Cómo funciona?

Web

Ofrecemos un proceso estándar de correspondencia de cookies cuando trabajamos con socios de audiencia MPP para identificar segmentos con fines de compra de medios en X. Además, los anunciantes pueden configurar una X Web Event Tag para recopilar datos de usuarios del sitio web y crear una Custom Audience correspondiente.

Pasos de configuración

¿Cómo funciona?

Mobile

Consulta la publicación del blog Custom Audiences from Mobile Apps para obtener más detalles.

Flexible

Flexible audiences ofrecen a los anunciantes la capacidad de crear y guardar combinaciones de audiencias basadas en custom audiences existentes o subconjuntos de custom audiences existentes. Los subconjuntos de los miembros de una custom audience pueden segmentarse en función de la recencia y la frecuencia de interacción.

Casos de uso restringidos para Custom Audiences

Más información sobre las restricciones

​

Preguntas frecuentes sobre audiencias

P: Enviamos una gran cantidad de datos, ¿por qué el tamaño de la audiencia aparece como TOO_SMALL?

R: Actualmente los datos se están agregando a la audiencia en tiempo real, pero el proceso que calcula el tamaño de la audiencia solo se ejecutará después de un periodo. El tamaño correcto de la audiencia debería mostrarse en la interfaz después de algunas horas.

P: Terminamos de enviar los datos de la audiencia y esperamos 24 horas o más, pero aún no podemos orientar la audiencia. ¿Qué debemos hacer a continuación?

R: Confirma lo siguiente:

• El user ID que se está enviando es correcto y no está malformado.
• Los nombres de audiencia que se están enviando son correctos y coinciden con actualizaciones de membresía anteriores.
• Confirma la respuesta de los comandos POST.
• Confirma que el píxel de ID Sync está implementado correctamente y que, según lo descrito por el proceso de ID Sync, suficientes usuarios han visitado el sitio en cuestión para mapear usuarios. Los usuarios no mapeados en las actualizaciones de membresía no se traducirán en usuarios segmentables.

Si todo lo demás se confirma como correcto y funcional, ponte en contacto con tus contactos de producto de X con información lo más detallada posible (consulta la Guía para solicitudes de socios como ejemplo de la información preferida).

P: ¿Cuántas veces podemos llamar al endpoint y con qué algoritmo?

R: Recomendamos encarecidamente que llames a nuestro sistema con deltas incrementales y que nunca reenvíes la membresía completa de la audiencia. El sistema se ha probado con un rendimiento suficiente para procesar actualizaciones incrementales de datos para algunos de los sitios web más grandes del mundo. La carga inicial de audiencias debe limitarse cuidadosamente y se espera que la primera carga tome una cantidad significativa de tiempo en completarse.

P: ¿Cuál es el tamaño mínimo para que una audiencia se use para segmentación?

• El tamaño mínimo para una audiencia es de 100 usuarios (después de la coincidencia). Si se hace match con una audiencia de menos de 500 usuarios, no estará disponible para segmentación en la UI de X Ads.

P: ¿Cuánto tiempo tomará procesar los archivos de la audiencia? ¿Y cuánto tiempo tardarán en estar listos en la Interfaz de Usuario de X?

• Normalmente toma entre 4 y 6 horas procesar los archivos de la audiencia, pero eso dependerá del tamaño del archivo. Una vez procesado, las audiencias están disponibles en la UI de X Ads.

P: ¿Cómo se calcula la tasa de coincidencia (match rate)?

• Tasa de coincidencia = usuarios activos en X en 90 días / número de usuarios proporcionados

P: ¿Cómo probamos si un archivo de audiencia funciona correctamente?

• Puedes proporcionar un archivo de audiencia de prueba y usar “keltonlynn” como handle del anunciante. Entonces podremos verificar que el archivo pueda ingerirse y cargarse correctamente en la UI de X.

P: ¿Qué es un identificador de usuario de partner (p_user_id)?

• Es el identificador que tu empresa utiliza para identificar de manera única a cada uno de tus clientes.

P: ¿Qué es un ID estándar?

• Puede ser una dirección de correo electrónico, un device ID, un X @handle o un ID.

P: ¿Cómo obtengo la HMAC Key?

• Se proporcionará por correo electrónico cifrado. Proporciona tu clave pública PGP a [e-mail] y te enviaremos un correo electrónico de prueba para verificar que todo funcione. Una vez verificado, te enviaremos la HMAC Key.

P: ¿Cómo verifico que el proceso de hashing funcionó usando la HMAC Key proporcionada?

• X proporcionará un archivo de prueba (que contiene direcciones de correo electrónico de muestra, device IDs, etc.) y un archivo de hash resultante con el cual podrás verificar tus resultados.

P: ¿Existe una limitación de tamaño para el archivo de full data match?

• No, no hay limitación de tamaño para el archivo de full data match.

P: ¿Cuánto tiempo tomará procesar el archivo de full data match?

• Una vez que X reciba el archivo, tomará aproximadamente 1 día procesarlo.

​

CRM

Este documento describe los detalles de integración para socios de CRM de Custom Audiences, incluidos los formatos de archivo y el proceso de intercambio de datos.

Resumen

La empresa proporcionará a X, en nombre de un cliente, una lista de identificadores de usuario comunes con hash (p. ej., direcciones de correo electrónico) o ids de usuario del socio para realizar una coincidencia a ciegas y generar una lista de X User IDs para la segmentación. Los segmentos de segmentación estarán disponibles para el @handle específico del anunciante indicado por el nombre de archivo en la configuración de la campaña en ads.x.com.

Todos los archivos de la empresa se enviarán a X mediante un paquete seguro en IronBox (www.golockbox.com) a través de una cuenta específica que X otorgue a la empresa. X proporcionará acceso a IronBox. La documentación sobre las APIs de IronBox está disponible en https://secure.goironcloud.com/Docs/Help/.

​

Requisitos de coincidencia de ID de socios

Si la empresa utiliza su propio sistema estándar de ID para rastrear usuarios (es decir, no identificadores de usuario comunes como direcciones de correo electrónico, ids de dispositivo, X user ID, etc.), este es el proceso recomendado.

1. Coincidencia completa de datos

Inicialmente, la Empresa proporcionará una lista completa de todos los registros de usuarios que incluya un identificador de usuario común único con X en un único archivo para realizar una coincidencia completa de datos y generar un mapeo, almacenado por X, de Partner IDs (p_user_id) a X IDs (tw_id). Esto se hará de forma periódica cada 2–3 meses para garantizar el mantenimiento adecuado. Una vez completada la coincidencia, X compartirá con la Empresa, por correo electrónico, una tasa de coincidencia de referencia a partir de este archivo.

El formato de este archivo debe ser:

Convención de nombres: FullDataMatch.[CompanyName].txt

Algoritmo de hash: HMAC_SHA-256

Formato:

Columna 1: valor con HMAC de los identificadores comunes

Columna 2: Partner User ID (único por usuario, no único en el archivo)

Delimitador de columnas (CSV): se usarán comas para delimitar el identificador de usuario común con hash del Partner ID

Valores separados por líneas

• Ej.: si el registro de usuario A tiene Partner User ID 1 y los identificadores comunes 1, 2 y 3:

common user identifier 1	p_user_1
common user identifier 2	p_user_1
common user identifier 3	p_user_1

*Consulta la sección de Instrucciones de hash para los identificadores de usuario comunes a continuación

2. Listas de segmentos personalizados

La Empresa proporcionará listas de usuarios en forma de p_user_id para crear audiencias personalizadas para clientes con el fin de realizar segmentación en X.

• Valores separados por líneas
• p_user_id
• • (Igual que lo proporcionado en la sección 1. Coincidencia completa de datos anterior. Si el valor proporcionado en la coincidencia completa de datos está con hash, la Empresa proporcionará el mismo valor con hash en el archivo de audiencia. Si el valor proporcionado no está con hash, la Empresa proporcionará el valor sin hash.)

​

Requisitos estándar de coincidencia

Si la empresa no utiliza un id estándar para el mapeo de todos los identificadores de usuarios de clientes, este es el proceso recomendado.

Listas de segmentos personalizados

La empresa proporcionará a X, en nombre de los clientes, listas de identificadores de usuario comunes con hash para crear audiencias personalizadas.

El formato de este archivo debe ser:

• Valores separados por líneas
• Identificador de usuario común con hash (p. ej., dirección de correo electrónico)
• Seguir las convenciones de nomenclatura de archivos indicadas a continuación
• Seguir las instrucciones de hashing para direcciones de correo electrónico a continuación (en Instrucciones de hashing)

​

Convenciones de nombres y operaciones de archivos de listas de segmentos personalizados

La operación de un archivo estará determinada por el nombre del archivo, con las siguientes operaciones disponibles y la convención general de nomenclatura de archivos: audiencename_partnername.handle.operation.filetype

• audiencename: El nombre de la Custom Audience. Este campo es el nombre que se mostrará al seleccionar la audiencia en la interfaz de configuración de campañas en ads.x.com, p. ej., brand_loyalty_card_holders.
• partnername: Nombre de la empresa que entrega los datos en nombre del anunciante, p. ej., company_name.
• handle: Cuenta de X (@handle) que tendrá acceso a las Custom Audiences, p. ej., @pepsi, @dietpepsi
• operation: new, add, remove, removeall, replace (detalles a continuación)
• : Marca de tiempo Unix epoch estándar en segundos, utilizada para garantizar que cada archivo de audiencia cargado sea único
• filetype: el archivo debe estar en formato *.txt

​

Creación y actualización de audiencias

Crea una nueva audiencia con un único archivo, p. ej., loyalty_card_holders_partnername.pepsi.new.txt

Add - Agrega las coincidencias de una lista a una audiencia existente, p. ej., loyalty_card_holders_partnername.pepsi.add..txt

Remove - Elimina las coincidencias de una lista de una audiencia existente. Ej.: loyalty_card_holders_partnername.pepsi.remove..txt

Remove All - Elimina, en todas las audiencias de ese cliente, las coincidencias derivadas de una lista acumulativa actualizada periódicamente (es decir, la lista de exclusión del cliente). Ej.: partnername.pepsi.removeall.txt

• Puede usarse para una lista integral de usuarios que se han dado de baja del Anunciante.
• X solo tendrá en cuenta la lista más reciente proporcionada en este archivo y la aplicará a todas las audiencias existentes y futuras donde haya coincidencias.

Usuarios de X en el momento en que se proporcionó y procesó este archivo.

Replace - Elimina una audiencia existente y la reemplaza por una nueva lista de audiencia. Ej.: loyalty_card_holders_partnername.pepsi.replace..txt

Exclusión general de la compañía - La compañía proporcionará un archivo acumulativo de exclusión para eliminar a los usuarios que se hayan dado de baja conforme a la política de exclusión de la compañía.

X solo tendrá en cuenta la lista más reciente proporcionada en este archivo de exclusión de la compañía y la aplicará a todas las audiencias existentes y futuras donde haya coincidencias con usuarios de X en el momento en que se proporcionó y procesó este archivo. El formato del archivo de exclusión de la compañía será el siguiente: Ej.: partnername.removeall.txt

Delete - Elimina una audiencia existente de la lista actual de audiencias, p. ej., loyalty_card_holders_partnername.pepsi.delete.txt

​

Instrucciones de hashing

X compartirá de forma segura, mediante PGP, una clave de producción codificada en base64 para aplicar hashing a identificadores comunes de usuarios (p. ej., direcciones de correo electrónico). La empresa decodificará la clave en base64 para obtener una clave de 32 bytes que se utilizará para realizar el hashing.

Ejemplo de clave codificada en base64:

BrQvOg+dACBUmKjRiNxZgJLh6zydjS0ZOv80FelTNzM=

Ejemplo de clave decodificada en base64:

/:� TшY

Normalización: La empresa realizará una normalización básica de los identificadores comunes de usuarios antes de aplicar el hashing (excepto en los Device IDs; consulta la sección de Normalización de Device ID).

​

Normalización de e‑mail

Es decir, eliminar los espacios iniciales y finales y convertir la dirección de e‑mail a minúsculas.

Ej.: Dirección de e‑mail sin procesar: [e-mail]

Después de la normalización: [e-mail]

Valor con hash: 74d9584eded0ad1e5572a1c1849f3716751d371d6117a6155dad5363f4b4fbec

Nota: La cantidad de caracteres tanto del HMAC codificado como de la clave puede variar según la entrada y la codificación; por lo tanto, el número exacto de caracteres puede diferir.

​

Normalización de ID de dispositivo

Aplicaremos los mismos requisitos para el hash de los ID de dispositivo usando el algoritmo SHA-256 y una sal común que proporcionamos a los socios de datos. Eliminamos los espacios, como hacemos con las direcciones de correo electrónico, pero no se realiza normalización a minúsculas para los IDFA/ID de Android y debe usarse el formato exacto del IDFA/ID de Android.

Aquí tienes un ejemplo del formato sin procesar de los ID de dispositivo para iOS y Android, antes del hash:

IDFA de iOS: DD99CFF7-6186-4602-9DF2-ED3FD0B2D431

ID de Android: b5bf2122961b3595

IDFA de iOS con hash: 134fb8cd95c7fd42e2793f469a447198ca5f990968db2dbadad70e723ed9750b

ID de Android con hash: 130dddff1939f229476f50bc8adab8fcb7e3525b0e9604fe8effc15e68cee4a4

​

Normalización del ID de usuario de X

Los IDs de X seguirán siendo hash, ya que la agrupación de datos (p. ej., la lista de clientes de @handles) es privada para el anunciante, aunque no sea PII. Mantendremos los mismos requisitos para aplicar hash a los IDs de X usando el algoritmo SHA-256 y una sal común que proporcionamos a los socios de datos. Se deben eliminar los espacios tanto del ID de X como del nombre de usuario, pero los IDs de usuario no requieren normalización. Los @usernames deben convertirse a minúsculas para la normalización. Además, el símbolo @ no debe incluirse como parte del nombre de usuario.

El formato de ID sin procesar será:

• ID de usuario: 27674040
• @username: testusername

ID de usuario con hash: bf6b57d4e861e83bea8bbed2b800b251a64c95468ee6e8cb07c3368c9ed45e85

@username con hash: 12201ae78ad1afa907c7112d17f498154ffb0bf9ea523f5390e072a06d7d9812

​

Integración de sincronización de ID

Los partners que envíen datos con un p_id deben completar un proceso de sincronización de ID para generar un mapeo entre los id de usuario del anunciante o partner y los id de usuario de X. Esto permite a los anunciantes orientar directamente a sus propios segmentos de usuarios en X. Los partners también deben establecer el valor del parámetro user_identifier_type en TALIST_PARTNER_USER_ID o TAWEB_PARTNER_USER_ID al enviar sus actualizaciones de membresía.

• Solo web: Esto se puede hacer colocando un píxel en el sitio del anunciante, como se describe a continuación.
• Lista: Esto se puede hacer utilizando cualquiera de los métodos descritos en la página de CRM.

​

URL del píxel

URL base
https://analytics.x.com/i/adsct

​

Parámetros del píxel

Parámetro	Descripción
p_id	Tu id de socio asignado por X
p_user_id	El id del usuario en el sistema del socio

​

Píxel de sincronización de ID:

Con un id de socio de ejemplo 111 y un p_user_id de ejemplo abc, el píxel resultante sería el siguiente:

    <pre class="brush: xml">
    <img height="1" width="1" src="https://analytics.x.com/i/adsct?p_id=111&p_user_id=abc" style="display:none" />
    </pre>

Configuración del archivo de exclusión y envío de archivos de exclusión

Los partners deben proporcionar a X una lista de usuarios que, según su mejor conocimiento, hayan optado por excluirse de la entrega de anuncios segmentados. El archivo debe tener el siguiente formato:

Número de columna	Nombre de la columna	Tipo de columna	Descripción
1	Partner ID	string	El “partner id” es el ID que X proporciona al partner para identificar de forma única a cada partner.
2	The user’s id in the partner system	string	El p_user_id es el ID único que utiliza el partner para identificar al usuario. El archivo que contiene estos usuarios excluidos debe cargarse mediante el endpoint TON upload y la ruta de los datos cargados debe enviarse al endpoint Global Opt Out aquí: PUT accounts/:account_id/custom_audiences/global_opt_out.

Envío de actualizaciones de membresía

Según se especifica en la documentación de nuestro endpoint, al enviar usuarios mediante el endpoint POST custom_audience_memberships se debe incluir un ID de cliente para habilitar una coincidencia basada en cookies. Los partners que envíen datos con un p_id deben establecer user_identifier_type en TALIST_PARTNER_USER_ID o TAWEB_PARTNER_USER_ID.

Todos los demás pasos seguirán siendo los mismos que los enumerados en la Guía de integración de la Audience API en tiempo real

​

Datos de usuario de Custom Audiences

Este documento describe el formato de los datos de usuario de [Custom Audience]/es/x-ads-api/audiences.

Normalización de datos

ID de dispositivo:

• IDFA: en minúsculas con guiones; p. ej.: 4b61639e-47cc-4056-a16a-c8217e029462
• AdID: se requiere el formato original del dispositivo; no en mayúsculas y con guiones; p. ej.: 2f5f5391-3e45-4d02-b645-4575a08f86e
• Android ID: se requiere el formato original del dispositivo; no en mayúsculas, sin guiones ni espacios; p. ej.: af3802a465767e36

Direcciones de correo electrónico:

• en minúsculas; elimina los espacios al inicio y al final; p. ej.: [e-mail]

Nombres de usuario de X:

• sin @; en minúsculas y sin espacios iniciales ni finales; p. ej.: jack

ID de usuario de X:

• Entero estándar; p. ej.: 143567

Hash de datos

Los datos de cada línea deben hashearse usando SHA256, sin salt. Además, el hash final debe estar en minúsculas. Por ejemplo, 49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d y no 49E0BE2AECCFB51A8DEE4C945C8A70A9AC500CF6F5CB08112575F74DB9B1470D

# hasheando el usuario @AdsAPI usando python
import hashlib
hashlib.sha256("adsapi".encode()).hexdigest()

#salida
49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d

Se pueden encontrar ejemplos de código adicionales para hashing en github.com/xdevplatform/ads-platform-tools.

​

Audiencias personalizadas: Web

Información

Los socios enviarán una lista de IDs (p_user_ids) para segmentar en nombre de un anunciante. Esto se realiza mediante un proceso de sincronización de IDs que crea una correspondencia entre los p_user_ids y el ID de usuario de X. Luego, esta correspondencia se utiliza para generar listas de IDs de usuario de X que pueden emplearse para la segmentación. Estas audiencias personalizadas estarán disponibles en el @handle específico del anunciante, indicado por la etiqueta en la configuración de campaña de Custom Audiences Web en ads.x.com.

X proporcionará el píxel seguro que puede añadirse a las etiquetas y sitios del socio para hacer coincidir los IDs (p_user_ids) con los IDs de usuario de X. Una vez completado el proceso de sincronización de IDs, los archivos de segmentación serán creados por el socio y estarán disponibles para X a través de un endpoint HTTPS. X incorporará estos archivos de segmentación de forma periódica y luego estarán disponibles en la interfaz de X.

Píxel seguro de X

El píxel seguro de X tendrá el siguiente aspecto:

https://analytics.x.com/i/adsct?p_user_id=xyz&p_id=123

p_user_id - xyz representa el ID de usuario del socio que proporciona el socio

p_id - 123 representa el ID único del socio (proporcionado por X)

Endpoint HTTPS del socio y archivo de usuarios para segmentación

El socio deberá proporcionar a X un endpoint HTTPS y credenciales (usuario/contraseña) que puedan utilizarse para incorporar el archivo de segmentación de forma periódica. Un endpoint HTTPS de ejemplo tendrá el siguiente aspecto:

https://<dominiosocio>/twitter/partner&#95;targeting_%Y-%M-%D.tsv.gz

%Y - Código de formato para el año (YYYY)

%M - Código de formato para el mes (MM)

%D - Código de formato para el día (DD)

Los datos transmitidos constarán de los siguientes archivos:

1. Archivo de usuarios de segmentación del Partner
2. Archivo de conversiones de segmentación

Todos los archivos estarán en formato TSV, donde los campos de cada fila están separados entre sí por un carácter de tabulación. Los valores válidos de los campos nunca contendrán el carácter de tabulación.

Rango de IP permitido de X:

Este es el rango de IP que se puede autorizar para el acceso al Partner Endpoint.

• 199.16.156.0/22
• 199.59.148.0/22

Archivo de usuarios de segmentación del Partner:

Número de columna	Nombre de columna	Tipo de columna	Descripción
1	partner id	string	El “partner id” es el ID que X proporciona al Partner para identificar de forma única a cada Partner.
2	advertiser id	string	El “advertiser id” es el @handle del anunciante.
3	p_user_id	string	El “p_user_id” es el ID único que el Partner utiliza para identificar al usuario.
3	confidence score	integer	El “confidence score” es opcional. Recomendamos usar un rango de 0 a 100. Si el caso de uso es retargeting, entonces un confidence score de “100” corresponde a un usuario que ha sido directamente reimpactado. Cualquier puntuación de 0 a 99 correspondería al nivel de confianza del similar (look-alike).
4	segment label	string	El “segment label” es opcional. Los Partners pueden usar “segment label” para especificar categorías de producto, por ejemplo. Recomendamos usar este “segment label”, ya que es el nombre legible para humanos de las Custom Audiences en la interfaz de ads.x.com.

Notas:

Cada vez que recibamos un nuevo Archivo de segmentación del Partner, esperamos que sea la lista completa de usuarios que el Partner nos recomienda segmentar, no incremental, a menos que se acuerde lo contrario. Acordaremos con cada Partner la frecuencia de entrega de este Archivo de segmentación del Partner. Si no recibimos un Archivo de segmentación del Partner según lo esperado, utilizaremos la versión anterior con un tiempo de expiración predefinido.

​

Integración de la API de Audiencias

​

Descripción general

La Audience API se lanzó como parte de v4 de la Ads API y, con ella, incorpora varias mejoras a los endpoints heredados de Audiences. Este nuevo endpoint se basa en un nuevo backend de procesamiento de Audiences y ofrece varias mejoras en términos de estabilidad, solidez y fiabilidad. El propósito de esta guía es destacar las diferencias entre la Audience API y los procesos heredados de carga y gestión de Audiences.

La documentación de referencia se encuentra en la página de documentación de referencia de la Audience API.

Nota: Todos los datos de usuario de Audience deben estar hasheados con SHA-256 antes de la carga. Puedes encontrar más detalles, junto con los tipos de identificadores de usuario aceptados y la normalización de datos, en la página de user data.

Cambios en la funcionalidad de Audience

Los siguientes cambios en las Custom Audiences se han introducido a partir de la v4 y cualquier endpoint obsoleto dejará de estar disponible una vez que se retire la v3 de la Ads API:

• Obsoleto TON Upload:
  • GET accounts/:account_id/custom_audience_changes
  • GET accounts/:account_id/custom_audience_changes/:custom_audience_change_id
  • POST accounts/:account_id/custom_audience_changes
  • PUT accounts/:account_id/custom_audiences/global_opt_out
• Obsoleto Real Time Audiences:
  • POST custom_audience_memberships
• Custom Audience:
  • El parámetro list_type se eliminará de la solicitud y la respuesta en todos los endpoints de Custom Audience. Este parámetro se usaba anteriormente para identificar el tipo de identificador de usuario de la Audience (es decir, email, X User ID, etc.); sin embargo, ahora las Audiences pueden aceptar múltiples identificadores de usuario para la misma Audience, por lo que este valor deja de ser relevante.
• General:
  • La ventana de retroactividad de la Audience se ha actualizado para hacer coincidir a usuarios activos en los últimos 90 días (antes 30 días)
  • El número mínimo de usuarios coincidentes requerido para que una audiencia sea segmentable se ha reducido a 100 usuarios (antes 500 usuarios)

Requisitos previos

• Acceso a Ads API
• Para acceder al endpoint de Audience, deberás ser añadido a una allowlist. Completa este formulario y acepta el nuevo X Ads Products and Services Agreement si la aceptación inicial fue anterior al 2018-08-01

Proceso de carga de Audience

La siguiente tabla enumera las diferencias principales entre los flujos antiguos y nuevos de creación de Audience, con más detalles disponibles más abajo:

Paso en el proceso	Audience API	(Obsoleto) TON Upload
Crear una Audience inicial	Se puede crear mediante el endpoint POST custom_audience	Se puede crear mediante el endpoint POST custom_audience
Agregar un nuevo usuario	Usa operation_type Update con el endpoint de Audience	Usa operation ADD con el endpoint POST custom_audience_changes
Eliminar un usuario	Usa operation_type Delete con el endpoint de Audience	Usa operation REMOVE con el endpoint POST custom_audience_changes
Excluir usuarios (opt-out)	Usa operation_type Delete con el endpoint de Audience y los custom_audience_id correspondientes de los que el usuario forma parte	Usa el endpoint de Global opt-out

Nota Cualquier audiencia que se actualice o se excluya (opt-out) a través de la ruta de TON Upload debe tener una lista correspondiente cargada mediante el endpoint TON Upload y asociada con una Audience usando el endpoint custom_audience_changes.

Limitación de tasa

El endpoint de Audience API tiene un límite de 1500/1min por cuenta. No hay límites en la cantidad de usuarios que se pueden enviar en un único payload. Las únicas restricciones del payload son:

1. Número total de operaciones: 2500 operaciones

2. Tamaño máximo del payload: 5,000,000 bytes

Gestión de usuarios de Audience

Para crear una nueva Audience, se requieren los siguientes pasos

​

Crear una nueva Audiencia personalizada

Crea un nuevo “contenedor” de Audiencia personalizada usando el endpoint [POST custom_audience]/es/x-ads-api/audiences y obtén el id de la Audiencia personalizada correspondiente. Este paso es obligatorio si creas una Audiencia desde cero. Si vas a actualizar una Audiencia existente, pasa a la siguiente sección

​

Agregar usuarios a una audiencia

Usa POST accounts/:account_id/custom_audiences/:custom_audience_id/users con el id de la Custom Audience y un ejemplo de payload como el siguiente:

POST https://ads-api.x.com/11/accounts/18ce54d4x5t/custom_audiences/1nmth/users

    # Todos los valores deben estar hasheados; los valores sin hashear se usan en este ejemplo con fines ilustrativos
    [
      {
        "operation_type": "Update",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "email": [
                "[e-mail]"
              ],
              "handle": [
                "x",
                "adsapi"
              ]
            },
            {
              "email": [
                "[e-mail]"
              ],
              "twitter_id": [
                "121291606",
                "17874544"
              ]
            }
          ]
        }
      }
    ]

Para agregar un usuario a una Audience, usa operation_type Update. La nueva interfaz de Audience permite enviar varias claves de usuario para un mismo usuario. Cada objeto en la matriz de objetos JSON corresponde a un único usuario. Con el payload del ejemplo anterior, la solicitud agregará dos usuarios a una Audience: uno con email y handle, y otro con email y twitter_id.

​

Quitar usuarios de una audiencia

De forma similar al proceso descrito para agregar usuarios, es posible quitar usuarios de una audiencia de la siguiente manera:

POST https://ads-api.x.com/11/accounts/18ce54d4x5t/custom_audiences/1nmth/users

    # Todos los valores deben estar hasheados; los valores sin hashear se utilizan en este ejemplo con fines ilustrativos
    [
      {
        "operation_type": "Delete",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "email": [
                "[e-mail]"
              ],
              "twitter_id": [
                "783214",
                "1225933934"
              ]
            },
            {
              "email": [
                "[e-mail]"
              ],
              "twitter_id": [
                "121291606",
                "17874544"
              ]
            }
          ]
        }
      }
    ]

El operation_type debe establecerse en Delete y los usuarios se harán coincidir según cualquiera de las claves que estuvieran presentes al agregarlos a la audiencia. Por ejemplo, si un usuario se añadió a una audiencia usando email y twitter_id, ese mismo usuario se puede eliminar usando cualquiera de esas claves; es decir, email, twitter_id o ambas.

Además, es posible agregar y eliminar usuarios de una audiencia en la misma solicitud. El endpoint admite múltiples operation_type por solicitud.

​

Usuarios que han optado por no participar

Con la retirada del endpoint global de exclusión, los socios deben Delete a cualquier usuario que haya optado por no participar en alguna Audiencia. Hay varias formas de hacerlo:

1. Llevar un registro de qué usuarios pertenecen a qué Audiencias y eliminar a estos usuarios individualmente de cada Audiencia.
2. Eliminar al usuario de todas las Audiencias asociadas a una cuenta de Ads.

Prácticas recomendadas generales

• Recomendamos encarecidamente invocar este endpoint en lotes casi en tiempo real para evitar picos en las colas que tardan más en procesarse y, en general, generan carga innecesaria en nuestro sistema. Esto también garantiza que los usuarios estén disponibles antes para la segmentación de campañas.
• Una llamada de API correcta devolverá success_count y total_count, que corresponden al número de objetos user recibidos en la solicitud.
• Este endpoint es de naturaleza atómica; es decir, o bien toda la solicitud se procesa con éxito o, si se produce algún error, la solicitud completa falla. En caso de una respuesta de error, se recomienda a los consumidores de la API corregir el error y volver a intentar la solicitud con todo el payload.
• En caso de error, se recomienda a los socios utilizar un enfoque de retroceso exponencial con reintentos. Por ejemplo: reintentar inmediatamente tras el primer error, reintentar 1 minuto después del segundo error y reintentar 5 minutos después del tercer error consecutivo, y así sucesivamente.

​

Referencia de API

​

Insights de palabras clave

Ejecutar en Postman

​

GET insights/keywords/search

Dado un grupo de palabras clave, obtén el volumen de Tweets asociado y un conjunto de 30 palabras clave relacionadas. El volumen de Tweets corresponde únicamente a las palabras clave de entrada, no a las relacionadas.

Se permite un intervalo de tiempo máximo (end_time - start_time) de 7 días.

Ten en cuenta que los resultados están restringidos a una única ubicación geográfica (país).

Resource URL

https://ads-api.x.com/12/insights/keywords/search

Parameters

Name	Description
granularity required	Especifica la granularidad de los datos devueltos para el intervalo de tiempo definido por start_time y end_time. Por ejemplo, cuando se establece en HOUR, se mostrará un punto de datos por cada hora entre start_time y end_time. Type: enum Possible values: DAY, HOUR
keywords required	Cadena de palabras clave separadas por comas para acotar la búsqueda. Todas las palabras clave se combinan con OR entre sí. Note: Se puede usar un máximo de 10 palabras clave (combinando keywords y negative_keywords). Type: string Example: developers
start_time required	Limita los datos recuperados a los recopilados en la ventana de tiempo entre start_time y end_time. Expresado en ISO 8601. Type: string Example: 2017-07-10T00:00:00Z
end_time optional	Limita los datos recuperados a los recopilados en la ventana de tiempo entre start_time y end_time. Expresado en ISO 8601. Note: De forma predeterminada, corresponde a la hora actual. Type: string Example: 2017-07-11T00:00:00Z
location optional	Un valor de segmentación que obtendrías del endpoint GET targeting_criteria/locations para acotar los resultados según la ubicación del usuario de la cuenta. Ten en cuenta que, por el momento, solo se admiten ubicaciones a nivel de país. Type: string Example: 0ce8b9a7b2742f7e
negative_keywords optional	Cadena de palabras clave separadas por comas para excluir. Todas las palabras clave negativas se combinan con OR entre sí. Note: Se puede usar un máximo de 10 palabras clave (combinando keywords y negative_keywords). Type: string Example: rain

Example Request

GET https://ads-api.x.com/12/insights/keywords/search?end_time=2018-02-02&granularity=DAY&keywords=developers&start_time=2018-02-01

Respuesta de ejemplo*

    {
      "request": {
        "params": {
          "start_time": "2018-02-01T00:00:00Z",
          "end_time": "2018-02-02T00:00:00Z",
          "granularity": "DAY",
          "keywords": [
            "developers"
          ]
        }
      },
      "data": {
        "related_keywords": [
          "dev",
          "developer",
          "coders",
          "mysql",
          "devs",
          "#technology",
          "#developers",
          "security",
          "programmers",
          "#tech",
          "javascript",
          "#iot",
          "#bigdata",
          "cloud",
          "devops",
          "php",
          "developer",
          "programmer",
          "engineer",
          "big data",
          "agile",
          "app",
          "programming",
          "ios",
          "maker",
          "startups",
          "developer's",
          "java",
          "#devops",
          "startup"
        ],
        "tweet_volume": [
          15707
        ]
      }
    }

​

Permisos de Audiencias personalizadas

Ejecutar en Postman

​

GET accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

Recupera los detalles de algunos o de todos los permisos asociados con la tailored audience especificada.

Resource URL

https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

Parameters

Name	Description
account_id required	El identificador de la cuenta utilizada. Aparece en la ruta del recurso y, por lo general, es un parámetro obligatorio para todas las solicitudes de la Advertiser API, excepto GET accounts. La cuenta especificada debe estar asociada al usuario autenticado. Type: string Example: 18ce54d4x5t
tailored_audience_id required	Una referencia a la tailored audience con la que operas en la solicitud. Type: string Example: 1nmth
count optional	Especifica la cantidad de registros que se intentará recuperar por cada solicitud. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Especifica un cursor para obtener la siguiente página de resultados. Consulta Pagination para obtener más información. Type: string Example: 8x7v00oow
granted_account_ids optional	Limita la respuesta únicamente a las cuentas deseadas especificando una lista de identificadores separados por comas. Se pueden proporcionar hasta 200 IDs. Type: string Example: 18ce54aymz3
sort_by optional	Ordena por un atributo compatible en orden ascendente o descendente. Consulta Sorting para obtener más información. Type: string Example: created_at-asc
tailored_audience_permission_ids optional	Limita la respuesta únicamente a los permisos de la tailored audience deseados especificando una lista de identificadores separados por comas. Se pueden proporcionar hasta 200 IDs. Type: string Example: ri
with_total_count optional	Incluye el atributo de respuesta total_count. Nota: Este parámetro y cursor son excluyentes. Nota: Las solicitudes que incluyan total_count tendrán límites de velocidad más bajos, actualmente establecidos en 200 por 15 minutos. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/1nmth/permissions

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "tailored_audience_id": "1nmth"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "tailored_audience_id": "1nmth",
          "permission_level": "READ_ONLY",
          "id": "ri",
          "created_at": "2017-06-08T23:17:59Z",
          "granted_account_id": "18ce54aymz3",
          "updated_at": "2017-06-08T23:17:59Z",
          "deleted": false
        }
      ]
    }

​

POST accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

Crea un nuevo objeto de permiso que permite compartir la audiencia especificada con una cuenta determinada.

Nota: Para crear o modificar permisos de una tailored audience, la audiencia debe pertenecer a la cuenta que intenta modificar los permisos. Puedes verificar la propiedad de una tailored audience consultando el atributo is_owner en la respuesta de la audiencia correspondiente.

Nota: Las audiencias solo pueden compartirse entre cuentas de anuncios del mismo negocio o si la cuenta de anuncios que posee la audiencia tiene la característica de cuenta SHARE_AUDIENCE_OUTSIDE_BUSINESS.

Resource URL

https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

Parameters

Name	Description
account_id required	Identificador de la cuenta utilizada. Aparece en la ruta del recurso y, por lo general, es un parámetro obligatorio para todas las solicitudes de la Advertiser API, excepto GET accounts. La cuenta especificada debe estar asociada al usuario autenticado. Type: string Example: 18ce54d4x5t
granted_account_id required	La cuenta a la que deseas otorgar permisos para la tailored audience. Type: string Example: 18ce54aymz3
permission_level required	El tipo de acceso a la tailored audience que debe tener granted_account_id. Type: enum Possible values: READ_ONLY, READ_WRITE
tailored_audience_id required	Referencia a la tailored audience con la que estás operando en la solicitud. Type: string Example: 2906h

Example Request

POST https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/2906h/permissions?granted_account_id=18ce54aymz3&permission_level=READ_ONLY

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "granted_account_id": "18ce54aymz3",
          "permission_level": "READ_ONLY",
          "tailored_audience_id": "2906h"
        }
      },
      "data": {
        "tailored_audience_id": "2906h",
        "permission_level": "READ_ONLY",
        "id": "14m",
        "created_at": "2017-09-12T23:49:34Z",
        "granted_account_id": "18ce54aymz3",
        "updated_at": "2017-09-12T23:49:34Z",
        "deleted": false
      }
    }

​

DELETE accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions/:tailored_audience_permission_id

Revoca el permiso de uso compartido de la Tailored Audience especificada.

Nota: Crear o modificar permisos para una Tailored Audience requiere que la audiencia sea propiedad de la cuenta que intenta modificar los permisos. Puedes verificar la titularidad de una Tailored Audience consultando el atributo de respuesta is_owner en la respuesta de la audiencia correspondiente.

Una vez revocado, garantizamos que la cuenta a la que se le concedió acceso (granted_account_id) no podrá segmentar la audiencia en campañas futuras. Las campañas existentes seguirán ejecutándose con las audiencias compartidas; las campañas no se detienen y la audiencia no se elimina de la campaña. No es posible copiar esa campaña después de revocar el permiso de uso compartido de la audiencia.

Resource URL

https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions/:tailored_audience_permission_id

Parameters

Nombre	Descripción
account_id required	El identificador de la cuenta utilizada. Aparece en la ruta del recurso y, por lo general, es un parámetro obligatorio para todas las solicitudes de la Advertiser API, excepto GET accounts. La cuenta especificada debe estar asociada con el usuario autenticado. Tipo: string Ejemplo: 18ce54d4x5t
tailored_audience_id required	Referencia a la Tailored Audience con la que operas en la solicitud. Tipo: string Ejemplo: 1nmth
tailored_audience_permission_id required	Referencia al permiso de la Tailored Audience con el que operas en la solicitud. Tipo: string Ejemplo: ri

Example Request

DELETE https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/1nmth/permissions/ri

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "tailored_audience_permission_id": "ri",
          "tailored_audience_id": "1nmth"
        }
      },
      "data": {
        "tailored_audience_id": "1nmth",
        "permission_level": "READ_ONLY",
        "id": "ri",
        "created_at": "2017-06-08T23:17:59Z",
        "granted_account_id": "18ce54aymz3",
        "updated_at": "2017-08-30T18:29:35Z",
        "deleted": true
      }
    }

​

Audiencias segmentadas

Ejecutar en Postman

​

GET accounts/:account_id/custom_audiences/:custom_audience_id/targeted

Obtiene una lista de partidas de línea y campañas (solo activas o todas) que segmentan un custom_audience_id dado

Name	Description
account_id required	Identificador de la cuenta utilizada. Aparece en la ruta del recurso y, por lo general, es un parámetro obligatorio para todas las solicitudes de la Advertiser API, excepto GET accounts. La cuenta especificada debe estar asociada al usuario autenticado. Tipo: string Ejemplo: 18ce54d4x5t
custom_audience_id required	Referencia a la audiencia personalizada con la que se opera en la solicitud. Tipo: string Ejemplo: 2906h
with_active optional	Cuando es false, incluye partidas de línea con estado servable=false Tipo: boolean Valor predeterminado: true Valores posibles: true, false
cursor optional	Especifica un cursor para obtener la página siguiente de resultados. Consulta Paginación para más información. Tipo: string Ejemplo: 8x7v00oow

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h/targeted

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_id": "2906h",
        }
      },
      "next_cursor": null,
      "data": [
        {
          "campaign_id": "59hod",
          "campaign_name": "test-campaign",
          "line_items": [
            {
              "id": "5gzog",
              "name": "test-line-item",
              "servable": true
            }
          ]
        },
        {
          "campaign_id": "arja7",
          "campaign_name": "Untitled campaign",
          "line_items": [
            {
              "id": "bjw1q",
              "name": null,
              "servable": true
            }
          ]
        }
      ]
    }

​

Usuarios de Audiences personalizadas

Ejecutar en Postman

​

POST accounts/:account_id/custom_audiences/:custom_audience_id/users

Este endpoint permite a los partners agregar, actualizar y eliminar usuarios de un custom_audience_id determinado. El endpoint también acepta múltiples tipos de identificadores por usuario.

Todos los datos proporcionados en el campo users de la solicitud, excepto partner_user_id, deben estar hasheados con SHA256 y normalizados.

Solicitudes por lotes

• El tamaño máximo actual del lote es de 2500 para este endpoint. El tamaño del lote se determina por el número de operaciones (Update/Delete) por solicitud. Por ejemplo, más de 2500 objetos de operación ({"operation_type": "Update/Delete", [..] }) en una sola matriz generan un error.
• El tamaño máximo del cuerpo de la solicitud POST que este endpoint puede aceptar es de 5,000,000 bytes.
• Los límites de tasa para este endpoint son 1500 por ventana de 1 minuto.
• Todos los parámetros se envían en el cuerpo de la solicitud y se requiere un Content-Type de application/json.
• Las solicitudes por lotes fallan o se completan correctamente en conjunto como grupo y todas las respuestas de la API, tanto de error como de éxito, preservan el orden de los elementos de la solicitud inicial.

Respuestas por lotes

La respuesta devuelta por la Ads API contiene dos campos: success_count y total_count. Estos valores siempre deben ser iguales y representan el número de registros de la solicitud que el backend ha procesado. Una situación en la que el número de registros enviados en el cuerpo de la solicitud no sea igual a success_count y total_count debe tratarse como una condición de error que requiere un reintento.

Errores por lotes

• Los errores a nivel de solicitud (p. ej., tamaño máximo de lote excedido) se muestran en la respuesta en el objeto errors.
• Los errores a nivel de elemento (p. ej., faltan parámetros obligatorios) se muestran en la respuesta en el objeto operation_errors.
• El índice del error en operation_errors corresponde al índice del elemento de entrada, con el mensaje de error correspondiente.

​

URL del recurso

https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/users

​

Parámetros

Nombre	Descripción
operation_type obligatorio	El tipo de operación por grupo de users que se realiza. Tipo: enum Valores posibles: Update, Delete
params obligatorio	Objeto JSON que contiene el array users y las marcas de tiempo effective_at y expires_at. Tipo: JSON
users obligatorio	Array de objetos JSON que contiene todos los parámetros de un usuario individual. Tipo: JSON
effective_at opcional	La hora UTC a la que deben entrar en vigor las asociaciones de audiencia personalizada. Expresado en ISO 8601. De forma predeterminada, la fecha y hora actuales. Tipo: string Ejemplo: 2017-07-05T07:00:00Z
expires_at opcional	La hora UTC a la que deben expirar las asociaciones de audiencia personalizada. La hora especificada debe ser posterior al valor de effective_at. Expresado en ISO 8601. De forma predeterminada, 13 meses desde la marca de tiempo de la solicitud. Tipo: string Ejemplo: 2017-07-05T07:00:00Z

Dado el enfoque de múltiples claves para el objeto users, cada elemento de este objeto se documenta a continuación:

Nombre	Descripción
email opcional	Dirección(es) de correo electrónico del usuario. Tipo: Array[String]
device_id opcional	IDFA/AdID/Android ID Tipo: Array[String]
handle opcional	El/los @handle(s) del usuario Tipo: Array[String]
twitter_id opcional	El id de X perteneciente al usuario Tipo: Array[String]
phone_number opcional	Número(s) de teléfono del usuario Tipo: Array[String]
partner_user_id opcional	El id del usuario en el sistema de los socios. Tipo: Array[String]

​

Ejemplo de solicitud

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/users

    [
      {
        "operation_type": "Actualizar",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "email": [
                "4798b8bbdcf6f2a52e527f46a3d7a7c9aefb541afda03af79c74809ecc6376f3"
              ],
              "handle": [
                "7352f353c460e74c7ae226952d04f8aa307b12329c5512ec8cb6f1a0f8f9b2cb",
                "49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d"
              ]
            },
            {
              "email": [
                "5bf13d5ad4200407c5bc8b9bb578e425d05ef936fd488e3799a9d0806669223c"
              ],
              "twitter_id": [
                "34d56c7159a7eea941f359653029410f813f65a1d2d13ecc5ccbdd5a8cb755cf",
                "00e7b76c9739dec57f4c4a20ec021a20ffcf26bd00f519b17ea00f0ed6048f85"
              ]
            }
          ]
        }
      },
      {
        "operation_type": "Eliminar",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "device_id": [
                "8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92"
              ],
              "email": [
                "4798b8bbdcf6f2a52e527f46a3d7a7c9aefb541afda03af79c74809ecc6376f3"
              ],
              "handle": [
                "461222f5dd690a20651c3d19848015cb0369db3f8e937571ffb775de70750847"
              ],
              "twitter_id": [
                "c623c7e163984493b46c547088542e95d0aaa529bc52bbecce3ff91eb6b7843b"
              ]
            },
            {
              "email": [
                "5bf13d5ad4200407c5bc8b9bb578e425d05ef936fd488e3799a9d0806669223c"
              ],
              "twitter_id": [
                "858cdc7f313f84a3f3c48e9a6323307c1ef1bb7439b8e3623e140454b0fd8fa5",
                "bb074e154657b91d99bd1bb3757409149670e8ae7a0fe9136fae29a26a7881c8"
              ]
            }
          ]
        }
      }
    ]

​

Ejemplo de respuesta

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_id": "1nmth"
        }
      },
      "data": {
        "success_count": 4,
        "total_count": 4
      }
    }

​

Permisos de Audiencia Personalizada

Ejecutar en Postman

​

GET accounts/:account_id/custom_audiences/:custom_audience_id/permissions

Obtén los detalles de algunos o todos los permisos asociados con la audiencia personalizada especificada.

URL del recurso

https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions

Parámetros

Nombre	Descripción
account_id obligatorio	El identificador de la cuenta utilizada. Aparece en la ruta del recurso y, por lo general, es un parámetro obligatorio para todas las solicitudes de la Advertiser API, excepto GET accounts. La cuenta especificada debe estar asociada con el usuario autenticado. Tipo: string Ejemplo: 18ce54d4x5t
custom_audience_id obligatorio	Una referencia a la audiencia personalizada con la que operas en la solicitud. Tipo: string Ejemplo: 1nmth
count opcional	Especifica la cantidad de registros que se intentará recuperar por cada solicitud independiente. Tipo: int Predeterminado: 200 Mín., Máx.: 1, 1000
cursor opcional	Especifica un cursor para obtener la página siguiente de resultados. Consulta Paginación para más información. Tipo: string Ejemplo: 8x7v00oow
granted_account_ids opcional	Limita la respuesta a las cuentas deseadas especificando una lista de identificadores separados por comas. Se pueden proporcionar hasta 200 IDs. Tipo: string Ejemplo: 18ce54aymz3
sort_by opcional	Ordena por el atributo admitido en orden ascendente o descendente. Consulta Ordenación para más información. Tipo: string Ejemplo: created_at-asc
custom_audience_permission_ids opcional	Limita la respuesta a los permisos de audiencia personalizada deseados especificando una lista de identificadores separados por comas. Se pueden proporcionar hasta 200 IDs. Tipo: string Ejemplo: ri
with_total_count opcional	Incluye el atributo de respuesta total_count. Nota: Este parámetro y cursor son excluyentes. Nota: Las solicitudes que incluyen total_count tendrán límites de frecuencia más bajos, actualmente establecidos en 200 por 15 minutos. Tipo: boolean Predeterminado: false Valores posibles: true, false

Solicitud de ejemplo

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/permissions

Respuesta de ejemplo

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_id": "1nmth"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "custom_audience_id": "1nmth",
          "permission_level": "READ_ONLY",
          "id": "ri",
          "created_at": "2017-06-08T23:17:59Z",
          "granted_account_id": "18ce54aymz3",
          "updated_at": "2017-06-08T23:17:59Z",
          "deleted": false
        }
      ]
    }

​

POST accounts/:account_id/custom_audiences/:custom_audience_id/permissions

Crea un nuevo objeto de permiso que permite compartir la audiencia especificada con una cuenta determinada.

Nota: Para crear o modificar permisos de una audiencia personalizada, la audiencia debe pertenecer a la cuenta que intenta modificarlos. Puedes verificar la titularidad de una audiencia personalizada consultando el atributo is_owner en la respuesta de la audiencia correspondiente.

Nota: Las audiencias solo se pueden compartir entre cuentas de anuncios del mismo negocio o si la cuenta de anuncios propietaria de la audiencia tiene la característica de cuenta SHARE_AUDIENCE_OUTSIDE_BUSINESS.

URL del recurso

https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions

Parámetros

Nombre	Descripción
account_id obligatorio	El identificador de la cuenta utilizada. Aparece en la ruta del recurso y, por lo general, es un parámetro obligatorio para todas las solicitudes de la Advertiser API, excepto GET accounts. La cuenta especificada debe estar asociada con el usuario autenticado. Tipo: string Ejemplo: 18ce54d4x5t
granted_account_id obligatorio	La cuenta a la que deseas otorgar permisos sobre la audiencia personalizada. Tipo: string Ejemplo: 18ce54aymz3
permission_level obligatorio	El tipo de acceso a la audiencia personalizada que debe tener granted_account_id. Tipo: enum Valores posibles: READ_ONLY, READ_WRITE
custom_audience_id obligatorio	Una referencia a la audiencia personalizada con la que estás operando en la solicitud. Tipo: string Ejemplo: 2906h

Solicitud de ejemplo

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h/permissions?granted_account_id=18ce54aymz3&permission_level=READ_ONLY

Respuesta de ejemplo

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "granted_account_id": "18ce54aymz3",
          "permission_level": "READ_ONLY",
          "custom_audience_id": "2906h"
        }
      },
      "data": {
        "custom_audience_id": "2906h",
        "permission_level": "READ_ONLY",
        "id": "14m",
        "created_at": "2017-09-12T23:49:34Z",
        "granted_account_id": "18ce54aymz3",
        "updated_at": "2017-09-12T23:49:34Z",
        "deleted": false
      }
    }

​

DELETE accounts/:account_id/custom_audiences/:custom_audience_id/permissions/:custom_audience_permission_id

Revoca el permiso de uso compartido de la Custom Audience especificada.

Nota: Crear o modificar permisos para una Custom Audience requiere que la audiencia pertenezca a la cuenta que intenta modificar los permisos. Puedes verificar la titularidad de una Custom Audience consultando el atributo de respuesta is_owner en la respuesta de la audiencia correspondiente.

Una vez revocado, garantizamos que la cuenta autorizada (granted_account_id) no podrá segmentar la audiencia en campañas futuras. Las campañas existentes seguirán ejecutándose con las audiencias compartidas; las campañas no se detienen y la audiencia no se elimina de la campaña. No es posible copiar esa campaña después de que se haya revocado el permiso de uso compartido de la audiencia.

URL del recurso

https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions/:custom_audience_permission_id

Parámetros

Nombre	Descripción
account_id obligatorio	El identificador de la cuenta utilizada. Aparece dentro de la ruta del recurso y, por lo general, es un parámetro obligatorio para todas las solicitudes de la Advertiser API, excepto GET accounts. La cuenta especificada debe estar asociada con el usuario autenticado. Tipo: string Ejemplo: 18ce54d4x5t
custom_audience_id obligatorio	Referencia a la Custom Audience con la que operas en la solicitud. Tipo: string Ejemplo: 1nmth
custom_audience_permission_id obligatorio	Referencia al permiso de la Custom Audience con el que operas en la solicitud. Tipo: string Ejemplo: ri

Ejemplo de solicitud

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/permissions/ri

Ejemplo de respuesta

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_permission_id": "ri",
          "custom_audience_id": "1nmth"
        }
      },
      "data": {
        "custom_audience_id": "1nmth",
        "permission_level": "READ_ONLY",
        "id": "ri",
        "created_at": "2017-06-08T23:17:59Z",
        "granted_account_id": "18ce54aymz3",
        "updated_at": "2017-08-30T18:29:35Z",
        "deleted": true
      }
    }

​

Audiencias personalizadas

Ejecutar en Postman

​

GET accounts/:account_id/custom_audiences

Obtiene los detalles de algunas o todas las Audiencias personalizadas asociadas a la cuenta actual.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/custom_audiences

Parameters

Name	Description
account_id required	El identificador de la cuenta utilizada. Aparece en la ruta del recurso y, por lo general, es un parámetro obligatorio para todas las solicitudes de la Advertiser API, excepto GET accounts. La cuenta especificada debe estar asociada con el usuario autenticado. Type: string Example: 18ce54d4x5t
count optional	Especifica la cantidad de registros que se intentará recuperar por cada solicitud. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Especifica un cursor para obtener la siguiente página de resultados. Consulta Pagination para más información. Type: string Example: 8x7v00oow
permission_scope optional	Permite filtrar la respuesta a listas que son de tu propiedad o listas que se hayan compartido contigo. De forma predeterminada, si no especificas este parámetro, solo verás las audiencias que te pertenecen. Type: enum Default: OWNER Possible values: OWNER, SHARED
q optional	Consulta opcional para acotar el recurso por name. Note: Realiza coincidencia de prefijo sin distinguir mayúsculas de minúsculas. Type: string Min, Max length: 1, 255
sort_by optional	Ordena por un atributo admitido en orden ascendente o descendente. Consulta Sorting para más información. Type: string Example: created_at-asc
custom_audience_ids optional	Limita la respuesta a las audiencias personalizadas deseadas especificando una lista de identificadores separados por comas. Se pueden proporcionar hasta 200 IDs. Type: string Example: 1nmth
with_deleted optional	Incluye resultados eliminados en la solicitud. Type: boolean Default: false Possible values: true, false
with_total_count optional	Incluye el atributo de respuesta total_count. Note: Este parámetro y cursor son excluyentes. Note: Las solicitudes que incluyan total_count tendrán límites de frecuencia más bajos, actualmente establecidos en 200 por cada 15 minutos. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences?custom_audience_ids=1nmth

Example Response

    {
      "request": {
        "params": {
          "custom_audience_ids": [
            "1nmth"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "targetable": true,
          "name": "twurl-using-subshell-for-file",
          "targetable_types": [
            "CRM",
            "EXCLUDED_CRM"
          ],
          "audience_type": "CRM",
          "description": null,
          "permission_level": "READ_WRITE",
          "owner_account_id": "18ce54d4x5t",
          "id": "1nmth",
          "reasons_not_targetable": [],
          "created_at": "2017-01-08T08:19:58Z",
          "updated_at": "2017-01-08T16:21:13Z",
          "partner_source": "OTHER",
          "deleted": false,
          "audience_size": 1470
        }
      ]
    }

​

GET accounts/:account_id/custom_audiences/:custom_audience_id

Obtén audiencias personalizadas específicas asociadas a la cuenta actual.

URL del recurso

https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id

Parámetros

Nombre	Descripción
account_id obligatorio	Identificador de la cuenta utilizada. Aparece en la ruta del recurso y, por lo general, es un parámetro obligatorio para todas las solicitudes de la Advertiser API, excepto GET accounts. La cuenta especificada debe estar asociada al usuario autenticado. Tipo: string Ejemplo: 18ce54d4x5t
custom_audience_id obligatorio	Referencia a la audiencia personalizada con la que operas en la solicitud. Tipo: string Ejemplo: 2906h
with_deleted opcional	Incluye resultados eliminados en tu solicitud. Tipo: boolean Valor predeterminado: false Valores posibles: true, false

Solicitud de ejemplo

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h

Respuesta de ejemplo

    {
      "request": {
        "params": {
          "custom_audience_id": "2906h",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "targetable": false,
        "name": "developers",
        "targetable_types": [
          "CRM",
          "EXCLUDED_CRM"
        ],
        "audience_type": "CRM",
        "description": null,
        "permission_level": "READ_WRITE",
        "owner_account_id": "18ce54d4x5t",
        "id": "2906h",
        "reasons_not_targetable": [],
        "created_at": "2017-08-22T23:34:26Z",
        "updated_at": "2017-08-22T23:34:26Z",
        "partner_source": "OTHER",
        "deleted": false,
        "audience_size": 140321
      }
    }

​

POST accounts/:account_id/custom_audiences

Crea una nueva audiencia personalizada de marcador de posición asociada a la cuenta actual.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/custom_audiences

Parameters

Name	Description
account_id required	El identificador de la cuenta utilizada. Aparece en la ruta del recurso y, por lo general, es un parámetro obligatorio para todas las solicitudes de la Advertiser API, excepto GET accounts. La cuenta especificada debe estar asociada con el usuario autenticado. Type: string Example: 18ce54d4x5t
name required	El nombre para mostrar de esta audiencia. Debe usarse un nombre único. De lo contrario, se producirá un error. Type: string Example: ads api users
description optional	Una descripción para esta audiencia. Type: string Example: Collection of all users of the Ads API

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences?name=developers

Example Response

    {
      "data": {
        "targetable": false,
        "name": "developers",
        "targetable_types": [
          "CRM",
          "EXCLUDED_CRM"
        ],
        "audience_type": "CRM",
        "description": null,
        "permission_level": "READ_WRITE",
        "owner_account_id": "18ce54d4x5t",
        "id": "2906h",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "created_at": "2017-08-22T23:34:26Z",
        "updated_at": "2017-08-22T23:34:26Z",
        "partner_source": "OTHER",
        "deleted": false,
        "audience_size": null
      },
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "name": "developers"
        }
      }
    }

​

PUT accounts/:account_id/custom_audiences/:custom_audience_id

Actualiza la Custom Audience específica asociada a la cuenta actual.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id

Parameters

Name	Description
account_id required	El identificador de la cuenta utilizada. Aparece en la ruta del recurso y, por lo general, es un parámetro obligatorio para todas las solicitudes de la Advertiser API, excepto GET accounts. La cuenta especificada debe estar asociada con el usuario autenticado. Type: string Example: 18ce54d4x5t
custom_audience_id required	Una referencia a la Custom Audience con la que se opera en la solicitud. Type: string Example: 2906h
name optional	El nombre para mostrar de esta audiencia. Debe usarse un valor de nombre único. De lo contrario, se producirá un error. Type: string Example: ads api users
description optional	Una descripción para esta audiencia. Type: string Example: Collection of all users of the Ads API

Example Request

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h?name=developers_changed

Example Response

    {
      "data": {
        "targetable": false,
        "name": "developers_changed",
        "targetable_types": [
          "CRM",
          "EXCLUDED_CRM"
        ],
        "audience_type": "CRM",
        "description": null,
        "permission_level": "READ_WRITE",
        "is_owner": true,
        "id": "2906h",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "created_at": "2017-08-22T23:34:26Z",
        "updated_at": "2017-08-22T23:34:26Z",
        "partner_source": "OTHER",
        "deleted": false,
        "audience_size": null
      },
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "name": "developers_changed"
        }
      }
    }

​

POST batch/accounts/:account_id/custom_audiences

Permite crear Audiencias personalizadas por lotes. Consulta la página Descripción general de Audiencias personalizadas para obtener información sobre audiencias.

Nota: Este endpoint por lotes está actualmente en beta cerrada y disponible para anunciantes seleccionados. Durante este período beta, solo se pueden crear Audiencias flexibles basadas en audiencias personalizadas móviles.

Solicitudes por lotes

• El tamaño máximo actual del lote es de 10.
• Todos los parámetros se envían en el cuerpo de la solicitud y se requiere Content-Type: application/json.
• Las solicitudes por lotes fallan o se completan correctamente en conjunto como un grupo, y todas las respuestas de la API, tanto de error como de éxito, preservan el orden de los elementos de la solicitud inicial.

Respuestas por lotes

Las respuestas de la API por lotes devuelven una colección ordenada de elementos. Por lo demás, su estructura es idéntica a la de sus endpoints correspondientes de un solo elemento.

Errores por lotes

• Los errores a nivel de solicitud (p. ej., tamaño máximo del lote excedido) se muestran en la respuesta en el objeto errors.
• Los errores a nivel de elemento (p. ej., falta un parámetro obligatorio) se muestran en la respuesta en el objeto operation_errors.

Audiencias flexibles

Ejecutar en Postman

• Las Audiencias flexibles son inmutables una vez creadas.
• Las Audiencias personalizadas se proporcionan en una estructura en árbol con combinaciones de lógica booleana para crear Audiencias flexibles.
• Se puede usar un máximo de 10 nodos hoja de Audiencias personalizadas para crear una Audiencia flexible.

URL del recurso

https://ads-api.x.com/12/batch/accounts/:account_id/custom_audiences

Parámetros

Name	Description
account_id required	El identificador de la cuenta utilizada. Aparece en la ruta del recurso y, por lo general, es un parámetro obligatorio para todas las solicitudes de la Advertiser API, excepto GET accounts. La cuenta especificada debe estar asociada al usuario autenticado. Tipo: string Ejemplo: 18ce54d4x5t
audience_type required	El tipo de audiencia que se va a crear. Tipo: enum Valores posibles: FLEXIBLE, MOBILE_AUDIENCE
child_segments required	Una matriz que contiene objetos que definen el subconjunto de miembros de una Custom Audience que deseas segmentar. Cada objeto debe contener custom_audience_id, frequency, frequency_comparator, lookback_window, negate y, en algunos casos, child_segments adicionales. Tipo: array
name required	El nombre para mostrar de la audiencia. Debe usarse un nombre único. De lo contrario, se producirá un error. Tipo: string Ejemplo: my_flexible_audience_name
operation_type required	El tipo de operación por elemento que se está realizando. Tipo: enum Valores posibles: Create, Update, Delete
boolean_operator sometimes required	La relación lógica entre los segmentos secundarios en su objeto padre (contenedor). Es obligatorio si child_segments no está vacío para el objeto padre. Tipo: enum Valores posibles: AND, OR
lookback_window sometimes required	Un valor entero que especifica el intervalo de días dentro del cual el usuario realizó la acción específica y calificó para la custom audience indicada. Tipo: int Valores posibles: 1, 7, 14, 30
segments sometimes required	Un objeto que contiene boolean_operator y child_segments, que definen el subconjunto de miembros de una Custom Audience que deseas segmentar. Tipo: object
custom_audience_id sometimes required	El id de la custom audience que se utilizará como segmento secundario. Tipo: string Ejemplo: tyfo
frequency optional	Un valor entero que especifica la frecuencia dentro de la ventana de retrospectiva en la que el usuario realizó la acción específica y calificó para la custom audience indicada. Tipo: int Valor predeterminado: 1
frequency_comparator optional	El comparador de la frequency enviada en la solicitud. Nota: En los valores siguientes, GTE significa mayor o igual que, LT menor que, y así sucesivamente. Tipo: string Valores posibles: NUM_GTE, NUM_GT, NUM_EQ, NUM_LTE, NUM_LT Valor predeterminado: NUM_GTE
negate optional	Niega el segmento y, por lo tanto, se excluye en la combinación. Tipo: boolean Valor predeterminado: true Valores posibles: true, false

Example Request

POST https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/custom_audiences

    [
      {
        "operation_type":"Create",
        "params":{
          "name":"nombre_de_mi_audiencia_flexible",
          "audience_type":"FLEXIBLE",
          "segments":{
            "boolean_operator":"AND",
            "child_segments":[
              {
                "custom_audience_id":"TYIF",
                "frequency":1,
                "frequency_comparator":"NUM_GT",
                "lookback_window":30,
                "negate":true,
                "child_segments":[

                ]
              },
              {
                "boolean_operator":"OR",
                "child_segments":[
                  {
                    "custom_audience_id":"TXR1",
                    "lookback_window":30,
                    "child_segments":[

                    ]
                  },
                  {
                    "custom_audience_id":"TYFO",
                    "frequency":1,
                    "frequency_comparator":"NUM_GT",
                    "lookback_window":30,
                    "negate":true,
                    "child_segments":[

                    ]
                  }
                ]
              }
            ]
          }
        }
      }
    ]

Ejemplo de respuesta

    {
      "data": {
        "targetable": false,
        "name": "my_flexible_audience_name",
        "targetable_types": [
          "FLEXIBLE",
          "EXCLUDED_FLEXIBLE"
        ],
        "audience_type": "FLEXIBLE",
        "id": "13ld7",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "metadata": [
          {
            "custom_audience_id": "13ld7",
            "account_id": "qsx3w2",
            "name": "my_flexible_audience_name",
            "audience_source": "FLEXIBLE_AUDIENCE",
            "upload_status": "UPLOADED",
            "segments": {
              "boolean_operator": "AND",
              "frequency": 1,
              "frequency_comparator": "NUM_GTE",
              "negate": false,
              "child_segments": [
                {
                  "custom_audience_id": "tyif",
                  "lookback_window": 30,
                  "frequency": 1,
                  "frequency_comparator": "NUM_GT",
                  "negate": true,
                  "child_segments": [

                  ]
                },
                {
                  "boolean_operator": "OR",
                  "frequency": 1,
                  "frequency_comparator": "NUM_GTE",
                  "negate": false,
                  "child_segments": [
                    {
                      "custom_audience_id": "txr1",
                      "lookback_window": 30,
                      "frequency": 1,
                      "frequency_comparator": "NUM_GTE",
                      "negate": false,
                      "child_segments": [

                      ]
                    },
                    {
                      "custom_audience_id": "tyfo",
                      "lookback_window": 30,
                      "frequency": 1,
                      "frequency_comparator": "NUM_GT",
                      "negate": true,
                      "child_segments": [

                      ]
                    }
                  ]
                }
              ]
            }
          }
        ],
        "created_at": "2015-11-10T21:26:43Z",
        "updated_at": "2015-11-11T01:11:47Z",
        "partner_source": "OTHER",
        "deleted": false,
        "audience_size": null
      },
      "request": [
        {
          "params": {
            "name": "my_flexible_audience_name",
            "audience_type": "FLEXIBLE",
            "segments": {
              "boolean_operator": "AND",
              "child_segments": [
                {
                  "custom_audience_id": "TYIF",
                  "lookback_window": 30,
                  "frequency": 1,
                  "frequency_comparator": "NUM_GT",
                  "negate": true,
                  "child_segments": [

                  ]
                },
                {
                  "boolean_operator": "OR",
                  "child_segments": [
                    {
                      "custom_audience_id": "TXR1",
                      "lookback_window": 30,
                      "child_segments": [

                      ]
                    },
                    {
                      "custom_audience_id": "TYFO",
                      "lookback_window": 30,
                      "frequency": 1,
                      "frequency_comparator": "NUM_GT",
                      "negate": true,
                      "child_segments": [

                      ]
                    }
                  ]
                }
              ]
            },
            "account_id": "qsx3w2"
          },
          "operation_type": "Create"
        }
      ]
    }

​

DELETE accounts/:account_id/custom_audiences/:custom_audience_id

Elimina la Custom Audience especificada que pertenece a la cuenta actual.

URL del recurso

https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id

Parámetros

Nombre	Descripción
account_id obligatorio	Identificador de la cuenta utilizada. Aparece en la ruta del recurso y, por lo general, es un parámetro obligatorio para todas las solicitudes de la Advertiser API, excepto GET accounts. La cuenta especificada debe estar asociada con el usuario autenticado. Tipo: string Ejemplo: 18ce54d4x5t
custom_audience_id obligatorio	Referencia a la custom audience con la que se opera en la solicitud. Tipo: string Ejemplo: 2906h

Ejemplo de solicitud

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h

Ejemplo de respuesta

    {
      "data": {
        "targetable": false,
        "name": "developers",
        "targetable_types": [
          "CRM",
          "EXCLUDED_CRM"
        ],
        "audience_type": "CRM",
        "description": null,
        "permission_level": "READ_WRITE",
        "owner_account_id": "18ce54d4x5t",
        "id": "2906h",
        "reasons_not_targetable": [
          "TOO_SMALL"
        ],
        "created_at": "2017-08-22T23:34:26Z",
        "updated_at": "2017-08-30T18:09:00Z",
        "partner_source": "OTHER",
        "deleted": true,
        "audience_size": null
      },
      "request": {
        "params": {
          "custom_audience_id": "2906h",
          "account_id": "18ce54d4x5t"
        }
      }
    }

​

Listas de No Contactar

Ejecutar en Postman

​

GET accounts/:account_id/do_not_reach_lists

Obtén los detalles de una o de todas las listas Do Not Reach asociadas con la cuenta actual.

Nota: Un account_id puede tener como máximo una lista Do Not Reach

URL del recurso

https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists

Parámetros

Nombre	Descripción
account_id obligatorio	El identificador de la cuenta utilizada. Aparece en la ruta del recurso y, por lo general, es un parámetro obligatorio para todas las solicitudes de la Advertiser API, excepto GET accounts. La cuenta especificada debe estar asociada con el usuario autenticado. Tipo: string Ejemplo: 18ce54d4x5t
with_deleted opcional	Incluir resultados eliminados en tu solicitud. Tipo: boolean Predeterminado: false Valores posibles: true, false

Ejemplo de solicitud

GET https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists

Ejemplo de respuesta

    {
      "request": {
        "params": {
          "account_id": "18ce54bgxky"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "targetable": false,
          "name": "Lista de no contactar",
          "description": "prueba de DNRL",
          "id": "4kzrq",
          "reasons_not_targetable": [
            "TOO_SMALL"
          ],
          "created_at": "2021-10-28T22:09:29Z",
          "list_size": null,
          "updated_at": "2021-11-04T03:33:06Z",
          "deleted": false
        }
      ]
    }

​

POST accounts/:account_id/do_not_reach_lists

Crea una nueva Do Not Reach List asociada a la cuenta actual.

Nota: Un account_id solo puede tener como máximo una Do Not Reach List

Resource URL

https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists

Parameters

Name	Description
account_id required	El identificador de la cuenta usada. Aparece en la ruta del recurso y, por lo general, es un parámetro obligatorio para todas las solicitudes de la Advertiser API, excepto GET accounts. La cuenta especificada debe estar asociada con el usuario autenticado. Tipo: string Ejemplo: 18ce54d4x5t
description optional	Descripción de esta audiencia. Tipo: string Ejemplo: A list of users to exclude

Example Request

POST https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists?description=A list of users to exclude

Example Response

    {
      "request": {
        "params": {
          "description": "Una lista de usuarios para excluir",
          "account_id": "18ce54bgxky"
        }
      },
      "data": {
        "targetable": false,
        "name": "Lista de No Contactar",
        "description": "Una lista de usuarios para excluir",
        "id": "4ofrq",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "created_at": "2022-02-08T23:02:48Z",
        "list_size": null,
        "updated_at": "2022-02-08T23:02:48Z",
        "deleted": false
      }
    }

​

POST batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users

Este endpoint permite agregar, actualizar y eliminar usuarios de un do_not_reach_list_id dado. Este endpoint solo acepta correos electrónicos como tipo válido de identificador de usuario.

Todos los datos proporcionados en el campo emails de la solicitud deben estar hasheados usando SHA256 y normalizados.

Notas

• Un account_id solo puede tener como máximo una Do Not Reach List
• Los usuarios agregados a esta lista deben tener una marca de tiempo expires_at establecida a menos de 13 meses desde la marca de tiempo actual
• La Do Not Reach List API no acepta una marca de tiempo effective_at y usa por defecto la marca de tiempo actual
• Do Not Reach List no elimina usuarios de ninguna ni de todas las audiencias personalizadas de la cuenta, sino que actúa como exclusión de segmentación para todas las campañas que se publican para la cuenta

Solicitudes por lotes

• El tamaño máximo actual del lote es 2500 para este endpoint. El tamaño del lote se determina por el número de operaciones (Update/Delete) por solicitud. Por ejemplo, más de 2500 objetos de operación ({"operation_type": "Update/Delete", [..] }) en una matriz generan un error.
• El tamaño máximo del cuerpo de la solicitud POST que puede aceptar este endpoint es de 5,000,000 bytes.
• Los límites de frecuencia para este endpoint son 1500 por ventana de 1 minuto
• Todos los parámetros se envían en el cuerpo de la solicitud y se requiere un Content-Type de application/json.
• Las solicitudes por lotes fallan o tienen éxito juntas como grupo y todas las respuestas de la API, tanto de error como de éxito, preservan el orden de los elementos de la solicitud inicial.

Respuestas por lotes

La respuesta devuelta por la Ads API contiene dos campos, success_count y total_count. Estos valores siempre deben ser iguales, y representan el recuento del número de registros en la solicitud que han sido procesados por el backend. Una situación en la que el número de registros enviados en el cuerpo de la solicitud no sea igual a success_count y total_count debe tratarse como una condición de error que requiere reintento.

Errores por lotes

• Los errores a nivel de solicitud (p. ej., tamaño máximo del lote excedido) se muestran en la respuesta bajo el objeto errors.
• Los errores a nivel de elemento (p. ej., parámetros obligatorios faltantes) se muestran en la respuesta bajo el objeto operation_errors.
• El índice del error en operation_errors se refiere al índice en el elemento de entrada, con el mensaje de error correspondiente

URL del recurso

https://ads-api.x.com/12/batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users

Parámetros

Name	Description
account_id required	El identificador de la cuenta utilizada. Aparece dentro de la ruta del recurso y, por lo general, es un parámetro obligatorio para todas las solicitudes de la Advertiser API, excepto GET accounts. La cuenta especificada debe estar asociada con el usuario autenticado. Type: string Example: 18ce54d4x5t
do_not_reach_list_id required	Una referencia a la Do Not Reach List con la que estás operando en la solicitud Type: string Example: 2906h
operation_type required	El tipo de operación por grupo de users que se está realizando. Type: enum Possible values: Update, Delete
params required	Un objeto JSON que contiene la matriz emails y la marca de tiempo expires_at. Type: JSON
users required	Una matriz de objetos JSON que contiene todos los parámetros para un usuario individual. Type: JSON
expires_at optional	La hora UTC a la que deben expirar las asociaciones del usuario. La hora especificada debe ser posterior a la marca de tiempo actual. Expresada en ISO 8601. De forma predeterminada, 13 meses desde la marca de tiempo actual. Type: string Example: 2017-07-05T07:00:00Z

Dado el enfoque de múltiples claves para el objeto users, cada elemento de este objeto se documenta a continuación:

Nombre	Descripción
email opcional	Dirección(es) de correo electrónico del usuario. Tipo: Array[String]
phone_number opcional	Número(s) de teléfono del usuario. Tipo: Array[String]

Solicitud de ejemplo

`POST https://ads-api.x.com/12/batch/accounts/18ce54bgxky/do_not_reach_lists/4kzro/users`

    [
      {
        "operation_type": "Update",
        "params": {
          "expires_at": "2023-01-22T00:00:00Z",
          "users": [
            {
              "email": [
                "FEAD76F6ADF99FFFB997AA4E3C8AD38FF531BC4C956DBD03CD0163F744D8AABC"
              ],
              "phone_number": [
                "CCABF1B62A202E0FE28BC6C014983C89A65451DD4482BD66A0ADB65366F38A9A"
              ]
            },
            {
              "email": [
                "FEAD76F6ADF99FFFB997AA4E3C8AD38FF531BC4C956DBD03CD0163F744D8AABA"
              ],
              "phone_number": [
                "CCABF1B62A202E0FE28BC6C014983C89A65451DD4482BD66A0ADB65366F38A9E"
              ]
            }
          ]
        }
      }
    ]

Ejemplo de respuesta

    {
      "data": [
        {
          "success_count": 2,
          "total_count": 2
        }
      ],
      "request": [
        {
          "params": {
            "do_not_reach_list_id": "4ofrq",
            "expires_at": "2023-01-22T00:00:00Z",
            "account_id": "18ce54bgxky"
          },
          "operation_type": "Update"
        }
      ]
    }

​

DELETE accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id

Elimina la lista Do Not Reach especificada perteneciente a la cuenta actual.

URL del recurso

https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id

Parámetros

Ninguno

Solicitud de ejemplo

DELETE https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists/4ofrp

Respuesta de ejemplo

    {
      "request": {
        "params": {
          "do_not_reach_list_id": "4ofrp",
          "account_id": "18ce54bgxky"
        }
      },
      "data": {
        "targetable": false,
        "name": "Lista de exclusión",
        "description": null,
        "id": "4ofrp",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "created_at": "2022-02-08T23:02:07Z",
        "list_size": null,
        "updated_at": "2022-02-08T23:02:21Z",
        "deleted": true
      }
    }