Audiencias

​

Audiencias personalizadas

​

Descripción general

Hay varias maneras de que los socios creen Custom Audiences.

• Audience API (CRM)
• Web
• Móvil
• Flexible

Ten en cuenta que no puedes excluir custom audiences similares (lookalike) de la segmentación. Además, no puedes segmentar a la vez una custom audience y una custom audience similar en la misma línea de anuncio (grupo de anuncios).

Gestión de audiencias

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

Para 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 gestionar audiencias, consulta la guía de Audience API.

Tiempos de procesamiento

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

Segmentación

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

Audience API (CRM)

Los socios de audiencias o socios de API proporcionan una lista de identificadores con hash y X realiza una coincidencia 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 coincidencia de cookies cuando trabajamos con socios de audiencias MPP para identificar segmentos a los que dirigirse en la 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 la Custom Audience correspondiente.

Pasos de configuración

¿Cómo funciona?

Móvil

Consulta la entrada de blog Custom Audiences from Mobile Apps para más detalles.

Flexible

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

Casos de uso restringidos para Custom Audiences

Lee más sobre las restricciones

​

Audiences FAQ

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

R: Actualmente los datos se están incorporando a la audiencia en tiempo real, pero el proceso que los trata para calcular el tamaño de la audiencia solo se ejecuta tras un período de tiempo. El tamaño correcto de la audiencia debería mostrarse en la interfaz de usuario 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 segmentar a la audiencia. ¿Cuáles deberían ser los siguientes pasos?

R: Confirma lo siguiente:

• El user ID que se está pasando es correcto y no está mal formado.
• Los nombres de audiencia que se están pasando son correctos y coinciden con las actualizaciones de membresía anteriores.
• Confirma la respuesta de los comandos POST.
• Confirma que el píxel de ID Sync está implementado correctamente y, como se describe en el proceso de ID Sync, que suficientes usuarios han visitado el sitio en cuestión como para poder mapearlos. Los usuarios no mapeados en las actualizaciones de membresía no se traducirán en usuarios segmentados.

Si todo lo demás se confirma como correcto y en funcionamiento, ponte en contacto con tus contactos de producto de X con información tan detallada como sea posible (consulta la Guide to Partner Inbounds como ejemplo del tipo de 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 vuelvas a enviar todas las membresías de la audiencia. Se ha probado que el sistema tiene 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 tarde una cantidad de tiempo significativa en completarse.

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

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

P: ¿Cuánto tiempo se tarda en procesar los archivos de audiencia? ¿Y cuánto tiempo se tarda en que los archivos de audiencia estén listos en la interfaz de usuario de X?

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

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

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

P: ¿Cómo probamos si un archivo de audiencia está funcionando correctamente?

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

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

• Es el identificador que utiliza tu empresa para identificar de forma ú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á mediante un 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 esté funcionando. 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 ejemplo, device IDs, etc.) y un archivo de hash resultante contra el que podrás verificar tus resultados.

P: ¿Hay una limitación de tamaño de archivo 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 se tardará en procesar el archivo de full data match?

• Una vez que X haya recibido el archivo, tardará aproximadamente 1 día en procesarlo.

​

CRM

Este documento describe los detalles de la integración para socios de CRM de Audiencias Personalizadas, 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 (es decir, direcciones de correo electrónico) o IDs de usuario del socio para realizar una coincidencia ciega y generar una lista de X User IDs para segmentación. Los segmentos para la segmentación estarán disponibles para la cuenta de anunciante específica con @handle indicada por el nombre de archivo en la configuración de campañas de ads.x.com.

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

​

Requisitos de coincidencia de ID de partner

Si la empresa utiliza su propio sistema estándar de ID para hacer seguimiento de usuarios (es decir, identificadores de usuario comunes como direcciones de correo electrónico, ids de dispositivo, X user ID, etc…) entonces 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 solo archivo para realizar una coincidencia completa de datos y generar una asignación, almacenada por X, de Partner IDs (p_user_id) a X IDs (tw_id). Esto se realizará regularmente cada 2-3 meses para garantizar un mantenimiento adecuado. Una vez completada la coincidencia, X compartirá con la empresa, por correo electrónico, una tasa de coincidencia de referencia derivada de este archivo.

El formato de este archivo debe ser:

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

Algoritmo de hashing: HMAC_SHA-256

Formato:

Columna 1: valor con hash HMAC de los identificadores comunes

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

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

Valores separados por saltos de línea

• Ej.: si el registro de usuario A tiene Partner User ID 1 y el identificador común 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

*Consulte la sección de instrucciones de hashing 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 para su segmentación en X.

• Valores separados por saltos de línea
• 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 tiene hash, entonces la empresa proporcionará el mismo valor con hash en el archivo de audiencia. Si el valor proporcionado no tiene hash, entonces 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 usuario de clientes, este es el proceso recomendado.

Listas de segmentos personalizados

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

El formato de este archivo debe ser:

• Valores separados por saltos de línea
• Identificador de usuario común con hash (es decir, 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 más abajo (en Instrucciones de hashing)

​

Convenciones de nombres y operaciones de archivos de segmentos personalizados

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

• audiencename: El nombre de la Audiencia personalizada (Custom Audience). Este campo es el nombre que se mostrará al seleccionar la audiencia en la interfaz de configuración de campañas de ads.x.com, por ejemplo brand_loyalty_card_holders.
• partnername: Nombre de la empresa que entrega los datos en nombre del anunciante, por ejemplo company_name.
• handle: Cuenta de X (@handle) que tendrá acceso a las Audiencias personalizadas, por ejemplo @pepsi, @dietpepsi.
• operation: new, add, remove, removeall, replace (detalles a continuación).
• : Marca de tiempo Unix epoch estándar en segundos, usada 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 audiencia nueva con un solo archivo, por ejemplo: loyalty_card_holders_partnername.pepsi.new.txt

Add - Agrega las coincidencias de una lista a una audiencia existente, por ejemplo: 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 las coincidencias generadas a partir de una lista acumulativa que se actualiza con regularidad de todas las audiencias de ese cliente (es decir, la lista de Opt-Out del cliente). Ej.: partnername.pepsi.removeall.txt

• Esto se puede usar para una lista completa de usuarios que se han excluido del anunciante.
• X solo respetará la lista más reciente proporcionada en este archivo y la aplicará a todas las audiencias existentes y futuras coincidentes para usuarios de X.

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

Overall Company Opt-Out - La empresa proporcionará un archivo de Opt-Out acumulativo para eliminar a los usuarios que se hayan excluido según la política de Opt-Out de la empresa.

X solo respetará la lista más reciente proporcionada en este archivo de Opt-Out de la empresa y la aplicará a todas las audiencias existentes y futuras para usuarios de X coincidentes en el momento en que se proporcionó y procesó este archivo. El formato del archivo de Opt-Out de la empresa será el siguiente: Ej.: partnername.removeall.txt

Delete - Elimina una audiencia existente de la lista actual de audiencias, por ejemplo: loyalty_card_holders_partnername.pepsi.delete.txt

​

Instrucciones de hashing

X compartirá de forma segura una clave de producción codificada en base64 mediante PGP para aplicar hashing a identificadores de usuario comunes (por ejemplo, direcciones de correo electrónico). La Empresa descodificará 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 descodificada de base64:

/:� TшY

Normalización: la Empresa realizará una normalización básica de los identificadores de usuario comunes antes de aplicar el hashing (excepto para los ID de dispositivo, consulta la sección Normalización de ID de dispositivo).

​

Normalización de correo electrónico

Es decir, eliminar los espacios iniciales y finales y también convertir la dirección de correo electrónico a minúsculas.

Ej.: Dirección de correo electrónico original: [e-mail]

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

Valor con hash: 74d9584eded0ad1e5572a1c1849f3716751d371d6117a6155dad5363f4b4fbec

Nota: La cantidad específica de caracteres tanto para el HMAC codificado como para la clave puede variar según la entrada y la codificación, por lo que el número concreto de caracteres puede diferir.

​

Normalización de ID de dispositivo

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

A continuación se muestra un ejemplo del formato sin procesar de los ID de dispositivo para iOS y Android, antes de aplicar el hash:

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

Android ID: b5bf2122961b3595

Hashed iOS IDFA: 134fb8cd95c7fd42e2793f469a447198ca5f990968db2dbadad70e723ed9750b

Hashed Android ID: 130dddff1939f229476f50bc8adab8fcb7e3525b0e9604fe8effc15e68cee4a4

​

Normalización de ID de usuario de X

Los ID de X seguirán sometiéndose a hashing, ya que la agrupación de datos (es decir, Lista de clientes de @handles) es privada para el anunciante, aunque no se considere información de identificación personal (PII). Tendremos los mismos requisitos para el hashing de los ID de X usando el algoritmo de hash SHA-256 y una sal común que proporcionamos a los socios de datos. Los espacios deben eliminarse tanto del ID de X como del @username, pero los ID de usuario no requieren normalización. Los @usernames deben convertirse a minúsculas para su normalización. Además, el símbolo @ no debe incluirse como parte del nombre de usuario.

El formato de ID sin procesar será:

• User ID: 27674040
• @username: testusername

Hashed User ID: bf6b57d4e861e83bea8bbed2b800b251a64c95468ee6e8cb07c3368c9ed45e85

Hashed @username: 12201ae78ad1afa907c7112d17f498154ffb0bf9ea523f5390e072a06d7d9812

​

Integración de sincronización de ID

Los partners que envían datos con un p_id deben llevar a cabo un proceso de sincronización de ID para generar un mapeo entre los ids de usuario del anunciante o del partner y los ids de usuario de X. Esto permite a los anunciantes dirigirse directamente a sus propios 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 web 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 identificador de socio asignado por X
p_user_id	El identificador del usuario en el sistema del socio

​

Píxel de sincronización de ID:

Usando un id de socio de ejemplo igual a 111 y un p_user_id de ejemplo igual a 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 no recibir anuncios segmentados. El archivo debe tener el siguiente formato:

Column Number	Column Name	Column Type	Description
1	Partner ID	string	El “partner id” es el ID que X proporciona al partner con el fin de 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 usando el endpoint TON upload y la ruta de los datos cargados debe enviarse al endpoint de exclusión global aquí: PUT accounts/:account_id/custom_audiences/global_opt_out.

Envío de actualizaciones de membresía

Como se especifica en nuestra documentación de endpoints, cuando se envían usuarios a través del endpoint POST custom_audience_memberships se debe proporcionar 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 indicados en la Real-Time Audience API Integration Guide.

​

Datos de usuario de Custom Audiences

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

Normalización de datos

Device IDs:

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

Direcciones de correo electrónico:

• en minúsculas, eliminando los espacios iniciales y finales; p. ej.: [e-mail]

Nombres de usuario de X:

• sin @, en minúsculas y sin espacios al inicio ni al final; p. ej.: jack

IDs de usuario de X:

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

Hashing de datos

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

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

#salida
49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d

Se pueden encontrar ejemplos de código adicionales para aplicar 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 (ID Sync) que construye 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ñas de Custom Audiences Web en ads.x.com.

X proporcionará el píxel seguro que se podrá insertar en 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. Estos archivos de segmentación se ingieren de forma regular en X y luego se ponen a disposición en la interfaz de usuario 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 es proporcionado por el socio

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

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

El socio tendrá que proporcionar a X un endpoint HTTPS y credenciales (nombre de usuario/contraseña) que se puedan usar para ingerir el archivo de segmentación de forma regular. Un ejemplo de endpoint HTTPS tendrá el siguiente aspecto:

https://<partnerdomain>/twitter/partner_targeting_%Y-%M-%D.tsv.gz

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

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

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

Los datos transmitidos consistirán en 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 individuales de cada fila están separados entre sí por un carácter de tabulación. Los valores de los campos válidos nunca contendrán el carácter de tabulación.

Rango de IP de X permitido:

Este es el rango de direcciones IP que se puede permitir para el acceso al endpoint del Partner.

• 199.16.156.0/22
• 199.59.148.0/22

Archivo de usuarios de segmentación del Partner:

Column Number	Column Name	Column Type	Description
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. Nuestra recomendación para el confidence score es usar valores de 0 a 100. Si el caso de uso es para retargeting, entonces un confidence score de “100” corresponde a un usuario que ha sido impactado directamente. Cualquier puntuación de 0-99 correspondería al nivel de confianza del usuario similar (look-alike).
4	segment label	string	El “segment label” es opcional. Los Partners pueden usar “segment label” para especificar, por ejemplo, categorías de producto. Nuestra recomendación es usar este “segment label”, ya que es el nombre legible por humanos para 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 cuál será 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 previsto, utilizaremos la versión anterior con un tiempo de vencimiento predefinido.

​

Integración de la Audience API

​

Descripción general

La Audience API se lanzó como parte de v4 de la Ads API y, con ello, incorpora varias mejoras respecto a los endpoints heredados de Audiences. Este nuevo endpoint utiliza un nuevo backend de procesamiento de Audiences y ofrece varias mejoras en términos de estabilidad, robustez y fiabilidad. El propósito de esta guía es resaltar 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 referencia de la Audience API. 

Nota: Todos los datos de usuarios de Audience deben estar hasheados con SHA-256 antes de la carga. Se pueden 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

Se han introducido los siguientes cambios en las Custom Audiences a partir de la v4, y cualquier endpoint en desuso dejará de estar disponible una vez que la v3 de la Ads API se haya retirado:

• En desuso 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
• En desuso Real Time Audiences:
  • POST custom_audience_memberships
• Custom Audience:
  • El parámetro list_type se eliminará de la solicitud y de la respuesta en todos los endpoints de Custom Audience. Este parámetro se utilizaba anteriormente para identificar el tipo de identificador de usuario de la Audience (es decir, correo electrónico, X User ID, etc.); sin embargo, ahora las Audiences tienen la capacidad de aceptar múltiples identificadores de usuario para la misma Audience, lo que hace que este valor deje de ser relevante.
• General:
  • La ventana de retrospectiva (lookback) de Audience se ha actualizado para hacer coincidir a los 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 la Ads API
• Para acceder al endpoint de Audience, tendrás que ser añadido a una lista de permitidos (allowlist). Completa este formulario y acepta el nuevo X Ads Products and Services Agreement si tu aceptación inicial fue anterior al 2018-08-01

Proceso de carga de Audience

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

Paso en el proceso	Audience API	(En desuso) TON Upload
Crear una Audience inicial (shell)	Se puede crear mediante el [POST custom_audience endpoint]/x-ads-api/audiences	Se puede crear mediante el [POST custom_audience endpoint]/x-ads-api/audiences
Añadir un nuevo usuario	Usa operation_type Update con el Audience endpoint	Usa operation ADD con el endpoint POST custom_audience_changes
Eliminar un usuario	Usa operation_type Delete con el Audience endpoint	Usa operation REMOVE con el endpoint POST custom_audience_changes
Excluir usuarios (opt-out)	Usa operation_type Delete con el Audience endpoint y los custom_audience_ids correspondientes de los que forma parte el usuario	Usa el Global opt-out endpoint

Nota: Cualquier Audience que se esté actualizando o excluyendo (opt-out) mediante la ruta de TON Upload debe tener una lista correspondiente cargada a través del endpoint TON Upload y asociada a una Audience usando el endpoint custom_audience_changes.

Limitación de tasa (rate limiting)

El endpoint de la Audience API tiene un límite de 1500/1 min por cuenta. No hay límites en el número de usuarios que se pueden enviar en una sola carga útil (payload). Las únicas restricciones sobre la carga útil son:

1. Número total de operaciones: 2500 operaciones

2. Tamaño máximo de la carga útil: 5,000,000 bytes

Gestión de usuarios de Audience

Para crear una nueva Audience, se requieren los pasos siguientes.

​

Crear una nueva Audiencia personalizada

Crea una nueva estructura inicial de Audiencia personalizada usando el endpoint [POST custom_audience]/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, salta 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 cuerpo de ejemplo como el siguiente:

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

    # Todos los valores deben estar en hash; los valores sin hash se usan en este ejemplo solo 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 pasar varias claves de usuario para un único usuario. Cada objeto en el array de objetos JSON corresponde a un solo usuario. Usando el payload de ejemplo anterior, la solicitud agregará dos usuarios a una Audience, uno con un email y un handle, y otro con un email y un twitter_id.

​

Eliminar usuarios de una audiencia

De forma similar al proceso descrito para agregar usuarios, los usuarios se pueden eliminar 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 en hash; los valores sin hash se utilizan en este ejemplo solo 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 identificarán mediante cualquiera de las claves que estuvieran presentes al agregarlos a la audiencia. Por ejemplo, si se agregó un usuario a una audiencia usando un email y un twitter_id, entonces se podrá eliminar al mismo usuario usando cualquiera de esas claves; es decir, email, twitter_id o ambos.

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

​

Usuarios con exclusión voluntaria

Con la retirada del endpoint global de exclusión voluntaria, se requiere que los partners ejecuten Delete para cualquier usuario que se haya excluido de cualquier Audiences. Hay varias maneras de lograr esto:

1. Hacer un seguimiento de qué usuarios forman parte de qué Audiences y eliminar estos usuarios individualmente de cada Audience.
2. Eliminar al usuario de todas las Audiences asociadas con una cuenta de Ads.

Mejores prácticas generales

• Recomendamos encarecidamente invocar este endpoint en lotes casi en tiempo real para evitar picos en las colas de procesamiento, que tardan más en completarse y, en general, generan una carga innecesaria en nuestro sistema. Esto también garantiza que los usuarios estén disponibles para la segmentación de campañas más rápidamente.
• Una llamada de API correcta devolverá un success_count y un total_count correspondientes al número de objetos user que se han recibido en la solicitud.
• Este endpoint es atómico por naturaleza; es decir, o bien toda la solicitud se procesa correctamente o, en caso de cualquier error, toda la solicitud fallará. 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 fallo, se recomienda a los partners usar un enfoque de retroceso exponencial con reintentos. Por ejemplo, reintentar inmediatamente después del primer fallo, reintentar después de 1 minuto tras el segundo fallo y reintentar después de 5 minutos tras el tercer fallo consecutivo, y así sucesivamente.

​

Referencia de la API

​

Información sobre palabras clave

​

GET insights/keywords/search

Dado un grupo de palabras clave, puedes obtener el volumen de Tweets asociado, así como un conjunto de 30 palabras clave relacionadas. El volumen de Tweets corresponde únicamente a las palabras clave de entrada, no a las palabras clave 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 limitados a una única ubicación geográfica (país).

URL del recurso

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

Parámetros

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 dato para cada hora entre start_time y end_time. Tipo: enum Valores posibles: DAY, HOUR
keywords required	Cadena de palabras clave separadas por comas para acotar la búsqueda. Todas las palabras clave se combinan mediante el operador OR entre sí. Nota: Se puede usar un máximo de 10 palabras clave (combinando keywords y negative_keywords). Tipo: string Ejemplo: developers
start_time required	Limita los datos recuperados a los datos recopilados en la ventana de tiempo entre start_time y end_time. Expresado en formato ISO 8601. Tipo: string Ejemplo: 2017-07-10T00:00:00Z
end_time optional	Limita los datos recuperados a los datos recopilados en la ventana de tiempo entre start_time y end_time. Expresado en formato ISO 8601. Nota: De forma predeterminada, se usa la hora actual. Tipo: string Ejemplo: 2017-07-11T00:00:00Z
location optional	Valor de segmentación que obtendrás del endpoint GET targeting_criteria/locations para acotar los resultados en función de dónde se encuentra el usuario de la cuenta. Ten en cuenta que, por el momento, solo se admiten ubicaciones a nivel de país. Tipo: string Ejemplo: 0ce8b9a7b2742f7e
negative_keywords optional	Cadena de palabras clave separadas por comas para excluir. Todas las palabras clave negativas se combinan mediante el operador OR entre sí. Nota: Se puede usar un máximo de 10 palabras clave (combinando keywords y negative_keywords). Tipo: string Ejemplo: rain

Solicitud de ejemplo

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

Ejemplo de respuesta*

    {
      "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

​

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

Recupera los detalles de algunos o todos los permisos asociados con la audiencia personalizada especificada.

URL del recurso

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

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, excluyendo GET accounts. La cuenta especificada debe estar asociada con el usuario autenticado. Type: string Example: 18ce54d4x5t
tailored_audience_id required	Una referencia a la audiencia personalizada con la que se opera en la solicitud. Type: string Example: 1nmth
count optional	Especifica el número de registros que se intentará recuperar por cada solicitud distinta. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Especifica un cursor para obtener la página siguiente de resultados. Consulta Pagination para más información. Type: string Example: 8x7v00oow
granted_account_ids optional	Limita la respuesta solo 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 admitido en orden ascendente o descendente. Consulta Sorting para más información. Type: string Example: created_at-asc
tailored_audience_permission_ids optional	Limita la respuesta solo a los permisos de audiencia personalizada 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 mutuamente excluyentes. Nota: Las solicitudes que incluyen total_count tendrán límites de tasa más bajos, actualmente establecidos en 200 por 15 minutos. Type: boolean Default: false Possible values: true, false

Ejemplo de solicitud

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

Ejemplo de respuesta

    {
      "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 permisos que permite compartir la audiencia especificada con una cuenta determinada.

Nota: Para crear o modificar permisos de una audiencia personalizada, es necesario que la audiencia sea propiedad de la cuenta que intenta modificar los permisos. Puedes comprobar la propiedad de una audiencia personalizada consultando el atributo de respuesta is_owner en la respuesta de una audiencia determinada.

Nota: Las audiencias solo se pueden compartir entre cuentas de anuncios dentro de la misma empresa o si la cuenta de anuncios que es propietaria de la audiencia tiene la función de cuenta SHARE_AUDIENCE_OUTSIDE_BUSINESS.

URL del recurso

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

Parámetros

Name	Description
account_id required	El identificador de la cuenta utilizada. Aparece dentro de la ruta del recurso y, en 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
granted_account_id required	La cuenta a la que deseas otorgar permisos sobre la audiencia personalizada. Type: string Example: 18ce54aymz3
permission_level required	El tipo de acceso a la audiencia personalizada que debería tener granted_account_id. Type: enum Possible values: READ_ONLY, READ_WRITE
tailored_audience_id required	Una referencia a la audiencia personalizada con la que estás operando en la solicitud. Type: string Example: 2906h

Ejemplo de solicitud

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

Ejemplo de respuesta

    {
      "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 audiencia personalizada especificada.

Nota: Crear o modificar permisos para una audiencia personalizada requiere que la audiencia sea propiedad de la cuenta que intenta modificar los permisos. Puedes comprobar la titularidad de una audiencia personalizada consultando el atributo de respuesta is_owner en la respuesta para una audiencia determinada.

Cuando se revoca, 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 esta campaña después de que se haya revocado 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

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
tailored_audience_id required	Una referencia a la audiencia personalizada con la que estás operando en la solicitud. Type: string Example: 1nmth
tailored_audience_permission_id required	Una referencia al permiso de audiencia personalizada con el que estás operando en la solicitud. Type: string Example: 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

​

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

Recupera una lista de elementos de línea y campañas activos, o de todos los elementos de línea y campañas, que segmentan a un custom_audience_id dado.

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 en GET accounts. La cuenta especificada debe estar asociada con el usuario autenticado. Type: string Example: 18ce54d4x5t
custom_audience_id required	Una referencia a la audiencia personalizada con la que estás operando en la solicitud. Type: string Example: 2906h
with_active optional	Cuando es false, incluye elementos de línea que tienen el estado servable=false. Type: boolean Default: true Possible values: true, false
cursor optional	Especifica un cursor para obtener la página siguiente de resultados. Consulta Pagination para obtener más información. Type: string Example: 8x7v00oow

Ejemplo de solicitud

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

Ejemplo de respuesta

    {
      "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 audiencias personalizadas

​

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

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

Todos los datos proporcionados en el campo users de la solicitud, excepto partner_user_id, deben convertirse a hash usando SHA256 y normalizarse.

Solicitudes por lotes

• El tamaño máximo actual de un 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 dan como resultado 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 de 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 Ads API contiene dos campos: success_count y total_count. Estos valores siempre deben ser iguales y representan un recuento del número de registros de 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 un reintento.

Errores por lotes

• Los errores a nivel de solicitud (por ejemplo, tamaño máximo de lote excedido) se muestran en la respuesta bajo el objeto errors.
• Los errores a nivel de elemento (por ejemplo, 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 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 required	El tipo de operación que se está realizando por grupo de users. Tipo: enum Valores posibles: Update, Delete
params required	Un objeto JSON que contiene el array users y las marcas de tiempo effective_at y expires_at. Tipo: JSON
users required	Un array de objetos JSON que contiene todos los parámetros para un usuario individual. Tipo: JSON
effective_at optional	La hora en UTC a la que la(s) asociación(es) de audiencia personalizada debe(n) entrar en vigor. Se expresa en ISO 8601. De manera predeterminada, es la fecha y hora actuales. Tipo: string Ejemplo: 2017-07-05T07:00:00Z
expires_at optional	La hora en UTC a la que la(s) asociación(es) de audiencia personalizada debe(n) expirar. La hora especificada debe ser posterior al valor de effective_at. Se expresa en ISO 8601. De manera predeterminada, es 13 meses después de la marca de tiempo de la solicitud. Tipo: string Ejemplo: 2017-07-05T07:00:00Z

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

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

​

Ejemplo de solicitud

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

    [
      {
        "operation_type": "Update",
        "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": "Delete",
        "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"
              ]
            }
          ]
        }
      }
    ]

​

Respuesta de ejemplo

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

​

Permisos de audiencia personalizada

​

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

Recupera 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

Name	Description
account_id required	El identificador de la cuenta utilizada. Aparece dentro de la ruta del recurso y, en general, es un parámetro obligatorio para todas las solicitudes de la Advertiser API, excluyendo GET accounts. La cuenta especificada debe estar asociada con el usuario autenticado. Type: string Example: 18ce54d4x5t
custom_audience_id required	Una referencia a la audiencia personalizada con la que se opera en la solicitud. Type: string Example: 1nmth
count optional	Especifica el número de registros que se intentará recuperar en 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
granted_account_ids optional	Restringe la respuesta solo 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 admitido en orden ascendente o descendente. Consulta Sorting para más información. Type: string Example: created_at-asc
custom_audience_permission_ids optional	Restringe la respuesta solo a los permisos de audiencia personalizada 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 incluyen total_count tendrán límites de tasa más bajos, actualmente establecidos en 200 por 15 minutos. Type: boolean Default: false Possible values: 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 que la audiencia especificada se comparta con una cuenta determinada.

Nota: Crear o modificar permisos para una audiencia personalizada requiere que la audiencia sea propiedad de la cuenta que intenta modificar los permisos. Puedes verificar si una audiencia personalizada es de tu propiedad consultando el atributo de respuesta is_owner en la respuesta de una audiencia determinada.

Nota: Las audiencias solo pueden compartirse entre cuentas de anuncios dentro de la misma empresa o si la cuenta de anuncios que es propietaria de la audiencia tiene la función de cuenta SHARE_AUDIENCE_OUTSIDE_BUSINESS.

Resource URL

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

Parameters

Name	Description
account_id required	El identificador de la cuenta utilizada. Aparece dentro de la ruta del recurso y, en general, es un parámetro obligatorio para todas las solicitudes de la Advertiser API, excluyendo GET accounts. La cuenta especificada debe estar asociada con el usuario autenticado. Type: string Example: 18ce54d4x5t
granted_account_id required	La cuenta a la que deseas conceder permisos para la audiencia personalizada. Type: string Example: 18ce54aymz3
permission_level required	El tipo de acceso a la audiencia personalizada que debe tener granted_account_id. Type: enum Possible values: READ_ONLY, READ_WRITE
custom_audience_id required	Una referencia a la audiencia personalizada con la que estás operando en la solicitud. Type: string Example: 2906h

Example Request

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

Ejemplo de respuesta

    {
      "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 compartición de la Custom Audience especificada.

Nota: Crear o modificar permisos para una custom audience requiere que la audiencia sea propiedad de la cuenta que intenta modificar los permisos. Puedes comprobar la propiedad de una custom audience consultando el atributo de respuesta is_owner en la respuesta para una audiencia determinada.

Cuando se revoca, 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 dicha campaña después de que se haya revocado el permiso de compartición 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

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. Tipo: string Ejemplo: 18ce54d4x5t
custom_audience_id required	Una referencia a la custom audience con la que estás operando en la solicitud. Tipo: string Ejemplo: 1nmth
custom_audience_permission_id required	Una referencia al permiso de custom audience con el que estás operando en la solicitud. Tipo: string Ejemplo: ri

Solicitud de ejemplo

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

Respuesta de ejemplo

    {
      "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

​

GET accounts/:account_id/custom_audiences

Obtiene los detalles de algunas o todas las audiencias personalizadas asociadas con 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 dentro de la ruta del recurso y, en 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 el número de registros que se intentarán recuperar por cada solicitud independiente. 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
permission_scope optional	Permite filtrar la respuesta a listas que son de tu propiedad o listas que se han compartido contigo. De forma predeterminada, si no se especifica este parámetro, solo verás las audiencias que son de tu propiedad. Type: enum Default: OWNER Possible values: OWNER, SHARED
q optional	Consulta opcional para limitar el recurso por name. Nota: Realiza una coincidencia de prefijo sin distinguir mayúsculas de minúsculas. Type: string Min, Max length: 1, 255
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
custom_audience_ids optional	Limita la respuesta únicamente a las audiencias personalizadas deseadas especificando una lista de identificadores separados por comas. Se pueden proporcionar hasta 200 ID. Type: string Example: 1nmth
with_deleted optional	Incluye resultados eliminados en tu solicitud. Type: boolean Default: false Possible values: true, false
with_total_count optional	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 tasa 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

Recupera 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

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, excluyendo GET accounts. La cuenta especificada debe estar asociada con el usuario autenticado. Tipo: string Ejemplo: 18ce54d4x5t
custom_audience_id required	Una referencia a la audiencia personalizada con la que se opera en la solicitud. Tipo: string Ejemplo: 2906h
with_deleted optional	Incluye resultados eliminados en la solicitud. Tipo: boolean Valor predeterminado: false Valores posibles: true, false

Ejemplo de solicitud

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

Ejemplo de respuesta

    {
      "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 provisional asociada con la cuenta actual.

URL del recurso

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

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, excluyendo 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 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: Colección de todos los usuarios de la Ads API

Ejemplo de solicitud

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

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": [
          "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 con la cuenta actual.

URL del recurso

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

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
custom_audience_id required	Una referencia a la Custom Audience con la que se está operando en la solicitud. Type: string Example: 2906h
name optional	El nombre para mostrar de esta audiencia. Se debe usar 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

Ejemplo de solicitud

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

Ejemplo de respuesta

    {
      "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 la creación por lotes de Audiencias Personalizadas. Consulta la página Descripción general de las Audiencias Personalizadas para obtener información sobre audiencias.

Nota: Este endpoint por lotes se encuentra actualmente en beta cerrada y está disponible para determinados anunciantes. Durante este periodo de 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 un Content-Type de application/json.
• Las solicitudes por lotes fallan o se procesan correctamente 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

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

Errores por lotes

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

Audiencias Flexibles

• Las Audiencias Flexibles son inmutables una vez creadas.
• Las Audiencias Personalizadas se pasan en una estructura de á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.

Resource URL

https://ads-api.x.com/12/batch/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. 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 audiencia personalizada que deseas segmentar. Cada objeto debe contener un custom_audience_id, frequency, frequency_comparator, lookback_window, negate y, en algunos casos, child_segments adicionales. Tipo: array
name required	El nombre visible de la audiencia. Debe usarse un valor de nombre único. De no hacerlo, 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 rango de días dentro del cual el usuario ha realizado la acción específica y ha calificado para la audiencia personalizada indicada. Tipo: int Valores posibles: 1, 7, 14, 30
segments sometimes required	Un objeto que contiene un boolean_operator y child_segments que definen el subconjunto de miembros de una audiencia personalizada que deseas segmentar. Tipo: object
custom_audience_id sometimes required	El id de la audiencia personalizada que se usará 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 ha realizado la acción específica y ha calificado para la audiencia personalizada indicada. Tipo: int Valor predeterminado: 1
frequency_comparator optional	El comparador para la frequency enviada en la solicitud. Nota: En los valores siguientes, GTE se refiere a mayor o igual que, LT a 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	Invierte el segmento y, por lo tanto, se excluye de 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":"my_flexible_audience_name",
          "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 audiencia personalizada (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

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, excluyendo GET accounts. La cuenta especificada debe estar asociada con el usuario autenticado. Tipo: string Ejemplo: 18ce54d4x5t
custom_audience_id required	Una referencia a la audiencia personalizada con la que se está operando 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 exclusión de alcance

​

GET accounts/:account_id/do_not_reach_lists

Recupera detalles de una o todas las listas Do Not Reach asociadas a la cuenta actual.

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

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 utilizada. Aparece en la ruta del recurso y, por lo general, es un parámetro obligatorio para todas las solicitudes de la Advertiser API, excluyendo GET accounts. La cuenta especificada debe estar asociada con el usuario autenticado. Tipo: string Ejemplo: 18ce54d4x5t
with_deleted optional	Incluye resultados eliminados en la solicitud. Tipo: boolean Valor predeterminado: false Valores posibles: true, false

Example Request

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

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54bgxky"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "targetable": false,
          "name": "Do Not Reach List",
          "description": "test 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 Lista de no contacto asociada con la cuenta actual.

Nota: Un account_id solo puede tener como máximo una Lista de no contacto.

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 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
description opcional	Una descripción para esta audiencia. Tipo: string Ejemplo: Una lista de usuarios que se deben excluir

Ejemplo de solicitud

POST https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists?description=Una lista de usuarios que se deben excluir

Ejemplo de respuesta

    {
      "request": {
        "params": {
          "description": "A list of users to exclude",
          "account_id": "18ce54bgxky"
        }
      },
      "data": {
        "targetable": false,
        "name": "Do Not Reach List",
        "description": "A list of users to exclude",
        "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 que se agreguen, actualicen y eliminen usuarios de un do_not_reach_list_id determinado. 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 tener un hash aplicado con SHA256 y estar normalizados.

Notas

• Un account_id solo puede tener como máximo una Lista de No Contactar.
• 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 API de Lista de No Contactar no acepta una marca de tiempo effective_at y, de forma predeterminada, usa la marca de tiempo actual.
• La Lista de No Contactar no elimina usuarios de ninguna audiencia personalizada de la cuenta, sino que actúa como segmentación de exclusión para todas las campañas atendidas 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 la cantidad 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 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 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, un success_count y un total_count. Estos valores siempre deben ser iguales y representan la cantidad de registros de la solicitud que han sido procesados por el backend. Una situación en la que la cantidad 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 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 del elemento de entrada, con el mensaje de error correspondiente.

Resource URL

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

Parameters

Name	Description
account_id required	El identificador de la cuenta utilizada. Aparece dentro de la ruta del recurso y, en general, es un parámetro obligatorio para todas las solicitudes de la Advertiser API, excluyendo 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 Lista de No Contactar con la que está 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 en la que la(s) asociación(es) del usuario debe(n) caducar. La hora especificada debe ser posterior al valor de la marca de tiempo actual. Se expresa en formato ISO 8601. De forma predeterminada, es 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:

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

Ejemplo de solicitud

`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"
              ]
            }
          ]
        }
      }
    ]

Respuesta de ejemplo

    {
      "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 asociada 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

Ejemplo de solicitud

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

Ejemplo de respuesta

    {
      "request": {
        "params": {
          "do_not_reach_list_id": "4ofrp",
          "account_id": "18ce54bgxky"
        }
      },
      "data": {
        "targetable": false,
        "name": "Do Not Reach List",
        "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
      }
    }