Audiencias

Audiencias Personalizadas

Descripción general

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

Audience API (CRM)
Web
Mobile
Flexible

Tenga en cuenta que no puede excluir las custom audiences de tipo lookalike de la segmentación. Además, no puede segmentar a la vez una custom audience y su lookalike en el mismo ad line item (ad group). Gestión de audiencias Las audiencias pueden gestionarse mediante partners de audiencias y partners de la X 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:

Para más detalles sobre cómo cargar y gestionar audiencias, consulte 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, 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 partners de audiencia o de API proporcionan una lista de identificadores con hash y X realiza la coincidencia y genera segmentos que se ponen a disposición para la compra de medios en X. Los partners pueden crear estas audiencias con la Audience API. ¿Cómo funciona?

Web Ofrecemos un proceso estándar de coincidencia de cookies cuando trabajamos con partners 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 la Custom Audience correspondiente. Pasos de configuración

¿Cómo funciona?

Mobile Consulte la publicación del blog sobre Custom Audiences from Mobile Apps para obtener más información. Flexible Flexible audiences brindan a los anunciantes la capacidad de crear y guardar combinaciones de audiencias basadas en custom audiences existentes o subconjuntos de estas. Se pueden segmentar subconjuntos de los miembros de una custom audience según la recencia y la frecuencia de la 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 incorporando a la audiencia en tiempo real, pero el proceso que calcula el tamaño de la audiencia solo se ejecuta pasado un período de tiempo. El tamaño correcto debería mostrarse en la interfaz después de unas horas. P: Terminamos de enviar datos de audiencia y esperamos 24 horas o más, pero aún no podemos segmentar la audiencia. ¿Qué debemos hacer a continuación? R: Confirme lo siguiente:

El id de usuario que se está pasando es correcto y no está malformado.
Los nombres de audiencia que se están pasando son correctos y coinciden con actualizaciones de membresía anteriores.
Confirme la respuesta de los comandos POST.
Verifique que el píxel de ID Sync esté implementado correctamente y que, según el proceso de ID Sync, hayan visitado el sitio suficientes usuarios para poder mapearlos. Los usuarios no mapeados en las actualizaciones de membresía no se convertirán en usuarios segmentables.

Si todo lo anterior se confirma como correcto y funcionando, póngase en contacto con sus interlocutores de producto de X con la información más detallada posible (consulte 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 llamar a nuestro sistema con deltas incrementales y no volver a enviar nunca todas las membresías de la audiencia. El sistema se ha probado con un rendimiento suficiente para procesar actualizaciones incrementales de datos de algunos de los sitios web más grandes del mundo. La carga inicial de audiencias debe controlarse cuidadosamente y se espera que la primera carga tarde un tiempo considerable en completarse. P: ¿Cuál es el tamaño mínimo para que una audiencia se utilice para la segmentación?

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

P: ¿Cuánto tiempo tardará en procesarse los archivos de audiencia? ¿Y cuánto tardarán en estar listos en la interfaz de usuario de X?

Por lo general, procesar los archivos de audiencia tarda entre 4 y 6 horas, dependiendo del tamaño del archivo. Una vez procesado, las audiencias están disponibles en la X Ads UI.

P: ¿Cómo se calcula la tasa de coincidencia?

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

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

Puede proporcionar un archivo de audiencia de prueba y usar “keltonlynn” como identificador del anunciante. Podemos verificar que el archivo se pueda ingerir y cargar correctamente en la X UI.

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

Es el identificador que su empresa utiliza para identificar de forma única a cada uno de sus clientes.

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

Puede ser una dirección de correo electrónico, un id de dispositivo, un @handle de X o un id.

P: ¿Cómo obtengo la clave HMAC?

Se proporcionará mediante un correo electrónico cifrado. Envíe su clave pública PGP a mpp-inquiry@x.com y le enviaremos un correo de prueba para verificar que todo funcione. Una vez verificado, le enviaremos la clave HMAC.

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

X proporcionará un archivo de prueba (que contiene direcciones de correo electrónico de ejemplo, ids de dispositivo, etc.) y un archivo de hash resultante con el que podrá verificar sus resultados.

P: ¿Existe alguna limitación de tamaño para el archivo de coincidencia de datos completo?

No, no hay ninguna limitación de tamaño para el archivo de coincidencia de datos completo.

P: ¿Cuánto tiempo tardará en procesarse el archivo de coincidencia de datos completo?

Una vez que X reciba el archivo, el procesamiento tardará aproximadamente 1 día.

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 (p. ej., direcciones de correo electrónico) o id de usuario del socio para realizar una coincidencia ciega y generar una lista de id de usuario de X 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 campaña de ads.x.com. Todos los archivos de la empresa se proporcionarán a X mediante un paquete seguro en IronBox (www.golockbox.com) a través de una cuenta específica otorgada a la empresa por X. X proporcionará acceso a IronBox. La documentación sobre las API de IronBox está disponible en https://secure.goironcloud.com/Docs/Help/.

Requisitos para la coincidencia de ID de socios

Si la empresa utiliza su propio sistema estándar de ID para hacer seguimiento de usuarios (es decir, no identificadores comunes de usuario como direcciones de correo electrónico, device ids, 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 común de usuario único con X en un solo 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 hash HMAC de los identificadores comunes Columna 2: Partner User ID (único por usuario; puede repetirse en el archivo) Delimitador de columnas (CSV): se utilizarán comas para delimitar el identificador común de usuario 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

*Consulte la sección de instrucciones de hash a continuación para los identificadores comunes de usuario 2. Listas de segmentos personalizados La empresa proporcionará listas de usuarios en la forma de p_user_id para crear audiencias personalizadas para clientes con fines de 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, entonces la empresa proporcionará el mismo valor con hash en el archivo de audiencia. Si el valor proporcionado no está con 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 los clientes, este es el proceso recomendado. Listas de segmentos personalizados La empresa proporcionará a X listas de identificadores de usuario comunes con hash directamente en nombre de los clientes 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 nomenclatura y operaciones de archivos de Listas de Segmentos Personalizados

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

audiencename: 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 de 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 Custom Audiences, p. ej., @pepsi, @dietpepsi
operation: new, add, remove, removeall, replace (detalles a continuación)
: Marca de tiempo Unix 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

Cree una nueva audiencia con un único archivo, p. ej., loyalty_card_holders_partnername.pepsi.new.txt Agregar - Agregue las coincidencias de una lista a una audiencia existente, p. ej., loyalty_card_holders_partnername.pepsi.add..txt Eliminar - Elimine las coincidencias de una lista de una audiencia existente. Ej.: loyalty_card_holders_partnername.pepsi.remove..txt Eliminar todo - Elimine las coincidencias generadas a partir de una lista acumulativa que se actualiza regularmente de todas las audiencias de ese cliente (es decir, la lista de exclusión del cliente). Ej.: partnername.pepsi.removeall.txt

Esto puede usarse 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á en todas las audiencias existentes y futuras para las coincidencias.

Usuarios de X en el momento en que se proporcionó y procesó este archivo. Reemplazar - Elimine una audiencia existente y reemplácela por una nueva lista de audiencia. Ej.: loyalty_card_holders_partnername.pepsi.replace..txt Exclusión general de la empresa - La empresa proporcionará un archivo acumulativo de exclusión para eliminar a los usuarios que se hayan excluido según la política de exclusión de la empresa. X solo respetará la lista más reciente proporcionada en este archivo de exclusión de la empresa y la aplicará en todas las audiencias existentes y futuras para los usuarios de X coincidentes en el momento en que se proporcionó y procesó este archivo. El formato del archivo de exclusión de la empresa será el siguiente: Ej.: partnername.removeall.txt Delete - Elimine 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 de usuario comunes (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 de usuario comunes antes de aplicar el hashing (excepto en los ID de dispositivo; consulte la sección Normalización de ID de dispositivo).

Normalización de correo electrónico

Es decir, elimina los espacios iniciales y finales y convierte la dirección de correo electrónico a minúsculas. Ej.: Dirección de correo electrónico sin procesar: testemail_Organisational_baseball+884@It92I6Ev2B.Com Después de la normalización: testemail_organisational_baseball+884@it92i6ev2b.com Valor de 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 que el número exacto de caracteres no es fijo.

Normalización de ID de dispositivo

Aplicaremos los mismos requisitos para el hash de los IDs de dispositivo utilizando 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 realizamos normalización a minúsculas para IDFA/Android ID y se debe utilizar el formato exacto del IDFA/Android ID. Aquí se muestra un ejemplo del formato bruto de IDs de dispositivo para iOS y Android, antes del hash: iOS IDFA: DD99CFF7-6186-4602-9DF2-ED3FD0B2D431 Android ID: b5bf2122961b3595 Hashed iOS IDFA: 134fb8cd95c7fd42e2793f469a447198ca5f990968db2dbadad70e723ed9750b Hashed Android ID: 130dddff1939f229476f50bc8adab8fcb7e3525b0e9604fe8effc15e68cee4a4

Normalización del id de usuario de X

Los id de X seguirán cifrándose mediante hash, ya que la agrupación de data —es decir, la Customer List de @handles— es privada para el anunciante aunque no sea PII. Tendremos los mismos requisitos para aplicar hash a los id de X usando el algoritmo SHA-256 y una sal común que proporcionamos a los socios de data. Deben eliminarse los espacios tanto del X id y del @username, pero los User IDs 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 username. 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íen data con un p_id deben completar un proceso de sincronización de ID para generar una correspondencia entre los ids de usuario del anunciante o del partner y los ids de usuario de X. Esto permite a los anunciantes dirigir 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 pertenencia.

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

URL del píxel


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

Parámetros de 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, han optado por no recibir anuncios segmentados. El formato del archivo debe ser el siguiente:


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	El id del usuario en el sistema del partner	string	El `p_user_id` es el ID único que el partner utiliza para identificar al usuario. El archivo que contiene estos usuarios excluidos debe cargarse utilizando el endpoint TON upload y la ruta de los data 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 del 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 data con un p_id deben establecer user_identifier_type en TALIST_PARTNER_USER_ID o TAWEB_PARTNER_USER_ID. Todos los demás pasos se mantienen iguales a los enumerados en la Guía de integración de la API de Audiencias en tiempo real

Datos de usuario de Custom Audiences

Este documento describe el formato de los [Custom Audience]/x-ads-api/audiences user data. Normalización de datos ID de dispositivo:

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

Direcciones de correo electrónico:

en minúsculas, sin espacios iniciales ni finales; p. ej., support@x.com

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 con SHA256, sin sal. Además, el hash de salida final debe estar en minúsculas. P. ej., 49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d y no 49E0BE2AECCFB51A8DEE4C945C8A70A9AC500CF6F5CB08112575F74DB9B1470D

# hashing 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 partners 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 ID que crea una asignación entre los p_user_ids y el ID de usuario de X. Esta asignación se utiliza después 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 de ads.x.com. X proporcionará el píxel seguro que puede insertarse en etiquetas y sitios de partners para hacer coincidir los IDs (p_user_ids) con IDs de usuario de X. Una vez completado el proceso de sincronización de ID, el partner creará los archivos de segmentación y los pondrá a disposición de X a través de un endpoint HTTPS. X ingerirá estos archivos de segmentación de forma periódica y, posteriormente, 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 partner proporcionado por el partner p_id - 123 representa el ID único del partner (proporcionado por X) Endpoint HTTPS del partner y archivo de usuarios para segmentación El partner deberá proporcionar a X un endpoint HTTPS y credenciales (nombre de usuario/contraseña) que puedan usarse para ingerir el archivo de segmentación de forma periódica. Un endpoint HTTPS de ejemplo 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 constarán de los siguientes archivos:

Archivo de usuarios de segmentación del partner
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 endpoint del partner.

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 manera unívoca 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 usa el partner 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 de retargeting, un confidence score de “100” indica un usuario que ha sido retargeted directamente. Cualquier puntuación de 0 a 99 corresponderá al nivel de confianza del 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. Recomendamos usar este “segment label”, ya que es el nombre legible para personas de las Audiencias personalizadas 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 recomienda segmentar, no incremental, salvo acuerdo en contrario. Acordaremos con cada partner la frecuencia de entrega de este archivo de segmentación. Si no recibimos un archivo de segmentación del partner según lo previsto, usaremos la versión anterior con un tiempo de expiración predefinido.

Integración de la API de Audiences

Descripción general

La Audience API se lanzó como parte de v4 de la X Ads API y, con ello, introduce varias mejoras respecto a los endpoints heredados de Audiences. Este nuevo endpoint se apoya en un nuevo backend de procesamiento de Audience y ofrece varias mejoras en estabilidad, solidez y confiabilidad. 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 Audience. La documentación de referencia está disponible en la página de documentación de referencia de la Audience API. Nota: Todos los datos de usuarios de Audience deben estar hasheados con SHA-256 antes de cargarse. Puede 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 A partir de la v4 se han introducido los siguientes cambios en Custom Audiences y cualquier endpoint en desuso dejará de estar disponible una vez que la v3 de la X Ads API se retire:

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 (p. ej., 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 lookback de Audience se actualizó para coincidir con usuarios activos dentro de 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 redujo a 100 usuarios (antes 500 usuarios)

Requisitos previos

Acceso a la X Ads API
Para acceder al endpoint de Audience, deberá agregarse a una allowlist. Complete este formulario y acepte el nuevo X Ads Products and Services Agreement si fue aceptado inicialmente antes del 2018-08-01

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

Paso en el proceso	Audience API	(Obsoleto) TON Upload
Crear una Audience base	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
Agregar un nuevo usuario	Use `operation_type` `Update` con el Audience endpoint	Use `operation` `ADD` con el endpoint POST custom_audience_changes
Eliminar un usuario	Use `operation_type` `Delete` con el Audience endpoint	Use `operation` `REMOVE` con el endpoint POST custom_audience_changes
Exclusión de usuarios (opt-out)	Use `operation_type` `Delete` con el Audience endpoint y los `custom_audience_id` correspondientes de los que el usuario forma parte	Use el Global opt-out endpoint

Nota Cualquier Audience que se esté actualizando o excluyendo mediante la ruta de TON Upload debe tener una lista correspondiente cargada a través del endpoint TON Upload y asociada con una Audience mediante el endpoint custom_audience_changes. Límite de tasa El endpoint de la Audience API tiene un límite de tasa de 1500/1min por cuenta. No hay límites en la cantidad de usuarios que se pueden enviar en una sola carga útil. Las únicas restricciones de la carga útil son:

Número total de operaciones: 2500 operaciones
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 siguientes pasos

Crear una nueva Audiencia Personalizada

Cree una nueva “plantilla” de Audiencia Personalizada con el endpoint [POST custom_audience]/x-ads-api/audiences y obtenga el id de la Audiencia Personalizada correspondiente. Este paso es obligatorio si va a crear una Audiencia desde cero. Si va a actualizar una Audiencia existente, pase a la siguiente sección.

Agregar usuarios a una audiencia

Utiliza 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 en hash, los valores sin hash 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": [
                "abc@x.com"
              ],
              "handle": [
                "x",
                "adsapi"
              ]
            },
            {
              "email": [
                "edf@x.com"
              ],
              "twitter_id": [
                "121291606",
                "17874544"
              ]
            }
          ]
        }
      }
    ]

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

Eliminar usuarios de una audiencia

De forma similar al proceso descrito para agregar usuarios, estos 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 usan 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": [
                "abc@x.com"
              ],
              "twitter_id": [
                "783214",
                "1225933934"
              ]
            },
            {
              "email": [
                "edf@x.com"
              ],
              "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 puede eliminarse usando cualquiera de esas claves; es decir, email, twitter_id o ambos. 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 excluidos (opt‑out)

Con la desaprobación del endpoint global de exclusión, los socios deben ejecutar DELETE para cualquier usuario que haya optado por excluirse de alguna Audiencia. Hay varias formas de lograrlo:

Llevar un registro de qué usuarios forman parte de qué Audiencias y eliminar a esos usuarios individualmente de cada Audiencia.
Eliminar al usuario de todas las Audiencias asociadas con 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 una 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 a la API exitosa devolverá success_count y total_count correspondientes a la cantidad de objetos user recibidos en la solicitud.
Este endpoint es atómico por naturaleza; es decir, o bien toda la solicitud se completa con éxito o, en caso de cualquier error, toda la solicitud fallará. Si se recibe una respuesta de error, se recomienda a los consumidores de la API corregir el problema y reintentar la solicitud con toda la carga útil.
En caso de error, se recomienda a los socios usar un enfoque de retroceso exponencial con reintentos. Por ejemplo, reintentar inmediatamente tras el primer error, reintentar después de 1 minuto tras el segundo error y reintentar después de 5 minutos tras el tercer error consecutivo, y así sucesivamente.

Referencia de la API

Información sobre palabras clave

GET insights/keywords/search

Dado un conjunto de palabras clave, obtén 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 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). 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 indicado 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	Una cadena de palabras clave separadas por comas para acotar la búsqueda. Todas las palabras clave se combinan mediante OR entre sí. Note: Puede usarse un máximo de 10 palabras clave (combinando `keywords` y `negative_keywords`). Type: string Example: `developers`
start_time required	Delimita 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	Delimita 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ás del endpoint GET targeting_criteria/locations para acotar resultados según la ubicación del usuario de la cuenta. Ten en cuenta que, por ahora, solo se admiten ubicaciones a nivel de país. Type: string Example: `0ce8b9a7b2742f7e`
negative_keywords optional	Una cadena de palabras clave separadas por comas para excluir. Todas las palabras clave negativas se combinan mediante OR entre sí. Note: Puede usarse 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 a Medida

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

Recupera los detalles de algunos o de todos los permisos asociados a la audiencia personalizada 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 con el usuario autenticado. Type: string Example: `18ce54d4x5t`
tailored_audience_id required	Una referencia a la audiencia personalizada con la que opera 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. Consulte Pagination para más información. Type: string Example: `8x7v00oow`
granted_account_ids optional	Limite 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. Consulte Sorting para más información. Type: string Example: `created_at-asc`
tailored_audience_permission_ids optional	Limite la respuesta únicamente 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`

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 audiencia personalizada, la audiencia debe ser 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 de la audiencia. Nota: Las audiencias solo pueden compartirse entre cuentas de anuncios pertenecientes a la misma empresa o si la cuenta de anuncios propietaria de 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, salvo 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 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`
tailored_audience_id required	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/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 Tailored Audience especificado. Nota: Crear o modificar permisos para una tailored audience requiere que la audiencia sea propiedad de la cuenta que intenta modificar los permisos. Puedes comprobar 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ó el 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	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	Referencia a la tailored audience con la que estás operando en la solicitud. Type: string Example: `1nmth`
tailored_audience_permission_id required	Referencia al permiso de la tailored audience 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 objetivo

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

Recupera una lista de partidas y campañas activas, o de todas, que segmentan un custom_audience_id determinado

Name	Description
account_id required	El identificador de la cuenta aprovechada. 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	Referencia a la audiencia personalizada con la que se opera en la solicitud. Type: string Example: `2906h`
with_active optional	Cuando es `false`, incluye partidas con estado `servable=false`. Type: boolean Default: `true` Possible values: `true`, `false`
cursor optional	Especifica un cursor para obtener la siguiente página de resultados. Consulta Pagination para más información. Type: string Example: `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": "campaña-de-prueba",
          "line_items": [
            {
              "id": "5gzog",
              "name": "elemento-de-línea-de-prueba",
              "servable": true
            }
          ]
        },
        {
          "campaign_id": "arja7",
          "campaign_name": "Campaña sin título",
          "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 partners añadir, 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 hashearse con SHA256 y normalizarse. 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 un array dan como resultado un error.
El tamaño máximo del cuerpo POST de la solicitud 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 procesan correctamente juntas 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 La respuesta devuelta por la X Ads API contiene dos campos: success_count y total_count. Estos valores siempre deben ser iguales y representan el conteo de los 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 (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 corresponde al índice del elemento de entrada, junto 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

Name	Description
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 `users` y las marcas de tiempo `effective_at` y `expires_at`. Type: JSON
users required	Una matriz de objetos JSON que contiene todos los parámetros de un usuario individual. Type: JSON
effective_at optional	La hora UTC a la que debe entrar en vigor la asociación de audiencia personalizada. Expresada en ISO 8601. De forma predeterminada, la fecha y hora actuales. Type: string Example: `2017-07-05T07:00:00Z`
expires_at optional	La hora UTC a la que debe expirar la asociación de audiencia personalizada. La hora especificada debe ser posterior al valor de `effective_at`. Expresada en ISO 8601. De forma predeterminada, 13 meses a partir de la marca de tiempo de la solicitud. Type: string Example: `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:

Name	Description
email optional	Dirección(es) de correo electrónico del usuario. Type: Array[String]
device_id optional	IDFA/AdID/Android ID Type: Array[String]
handle optional	El/los @handle del usuario Type: Array[String]
twitter_id optional	El id de X del usuario Type: Array[String]
phone_number optional	Número(s) de teléfono del usuario Type: Array[String]
partner_user_id optional	El id del usuario en el sistema del partner. Type: 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 Audiencias Personalizadas

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

Recupera 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 aprovechada. 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 obligatorio	Una referencia a la audiencia personalizada con la que está operando en la solicitud. Type: string Example: `1nmth`
count opcional	Especifica la cantidad de registros que se intentará recuperar por cada solicitud. Type: int Default: `200` Min, Max: `1`, `1000`
cursor opcional	Especifica un cursor para obtener la página siguiente de resultados. Consulte Pagination para más información. Type: string Example: `8x7v00oow`
granted_account_ids opcional	Limita la respuesta solo a las cuentas deseadas especificando una lista de identificadores separada por comas. Se pueden proporcionar hasta 200 IDs. Type: string Example: `18ce54aymz3`
sort_by opcional	Ordena por un atributo compatible en orden ascendente o descendente. Consulte Sorting para más información. Type: string Example: `created_at-asc`
custom_audience_permission_ids opcional	Limita la respuesta solo a los permisos de audiencia personalizada deseados especificando una lista de identificadores separada por comas. Se pueden proporcionar hasta 200 IDs. Type: string Example: `ri`
with_total_count opcional	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 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 compartir la audiencia especificada con una cuenta determinada. Nota: Para crear o modificar permisos de una audiencia personalizada, la audiencia debe ser propiedad de la cuenta que intenta modificar los permisos. Puede comprobar la titularidad de una audiencia personalizada consultando el atributo de respuesta 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 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 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`
granted_account_id required	La cuenta a la que desea 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á 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

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 audiencia personalizada especificada. Nota: Para crear o modificar permisos de una audiencia personalizada, la audiencia debe pertenecer a la cuenta que intenta modificar los permisos. Puede comprobar la titularidad de una audiencia personalizada revisando 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 que se haya revocado el permiso de uso compartido de la audiencia. Resource URL

https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions/:custom_audience_permission_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	Referencia a la audiencia personalizada con la que opera en la solicitud. Type: string Example: `1nmth`
custom_audience_permission_id required	Referencia al permiso de audiencia personalizada con el que opera en la solicitud. Type: string Example: `ri`

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

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_permission_id": "ri",
          "custom_audience_id": "1nmth"
        }
      },
      "data": {
        "custom_audience_id": "1nmth",
        "permission_level": "SOLO_LECTURA",
        "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

Recupera 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 al 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. Consulte Pagination para más información. Type: string Example: `8x7v00oow`
permission_scope optional	Permite filtrar la respuesta a listas que posee o listas que se han compartido con usted. De forma predeterminada, sin especificar este parámetro, solo verá audiencias que posee. Type: enum Default: `OWNER` Possible values: `OWNER`, `SHARED`
q optional	Una query opcional para acotar el recurso por `name`. Note: Realiza una coincidencia por prefijo sin distinción de mayúsculas y minúsculas. Type: string Min, Max length: `1`, `255`
sort_by optional	Ordena por el atributo admitido en orden ascendente o descendente. Consulte Sorting para más información. Type: string Example: `created_at-asc`
custom_audience_ids optional	Limite la respuesta únicamente 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	Incluya resultados eliminados en su solicitud. Type: boolean Default: `false` Possible values: `true`, `false`
with_total_count optional	Incluya el atributo de respuesta `total_count`. Note: Este parámetro y `cursor` son excluyentes. Note: Las solicitudes que incluyen `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/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 con 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	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	Referencia a la audiencia personalizada con la que se opera en la solicitud. Type: string Example: `2906h`
with_deleted optional	Incluir elementos eliminados en la respuesta de la solicitud. Type: boolean Default: `false` Possible values: `true`, `false`

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

    {
      "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 X Ads 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 valor de nombre único; de lo contrario, se producirá un error. Type: string Example: `ads api users`
description optional	Una descripción de 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 Audiencia personalizada específica asociada con 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 X Ads API, excepto GET accounts. La cuenta especificada debe estar asociada con el usuario autenticado. Type: string Example: `18ce54d4x5t`
custom_audience_id required	Referencia a la Audiencia personalizada con la que 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	Descripción de 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 la creación por lotes de Custom Audiences. Consulta la página Custom Audiences Overview para obtener información sobre audiencias. Nota: Este endpoint de lote está actualmente en beta cerrada y disponible para un grupo selecto de anunciantes. Durante este periodo beta, solo se pueden crear Flexible Audiences basadas en audiencias personalizadas móviles. Solicitudes por lote

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 lote fallan o se completan correctamente juntas 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 lote Las respuestas de la API por lote 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 lote

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

Flexible Audiences

Las Flexible Audiences son inmutables una vez creadas.
Las Custom Audiences se proporcionan en una estructura en árbol con combinaciones de lógica booleana para crear Flexible Audiences.
Se puede usar un máximo de 10 nodos hoja de Custom Audiences para crear una Flexible Audience.

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

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`
audience_type obligatorio	El tipo de audiencia que se va a crear. Tipo: enum Valores posibles: `FLEXIBLE`, `MOBILE_AUDIENCE`
child_segments obligatorio	Una matriz que contiene objetos que definen el subconjunto de miembros de una Custom Audience que desea 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 obligatorio	El nombre para mostrar de la audiencia. Debe usarse un valor de nombre único; de lo contrario, se producirá un error. Tipo: string Ejemplo: `my_flexible_audience_name`
operation_type obligatorio	El tipo de operación por elemento que se está realizando. Tipo: enum Valores posibles: `Create`, `Update`, `Delete`
boolean_operator a veces obligatorio	La relación lógica entre los segmentos secundarios en su objeto padre (contenedor). Obligatorio si `child_segments` no está vacío para el objeto padre. Tipo: enum Valores posibles: `AND`, `OR`
lookback_window a veces obligatorio	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 Custom Audience indicada. Tipo: int Valores posibles: `1`, `7`, `14`, `30`
segments a veces obligatorio	Un objeto que contiene un `boolean_operator` y `child_segments` que definen el subconjunto de miembros de una Custom Audience que desea segmentar. Tipo: object
custom_audience_id a veces obligatorio	El id de la Custom Audience que se usará como segmento secundario. Tipo: string Ejemplo: `tyfo`
frequency opcional	Un valor entero que especifica la frecuencia, dentro de la ventana de retrospectiva, con la que el usuario ha realizado la acción específica y ha calificado para la Custom Audience indicada. Tipo: int Valor predeterminado: `1`
frequency_comparator opcional	El comparador de la `frequency` enviada en la solicitud. Nota: En los valores a continuación, `GTE` significa mayor o igual que, `LT` menor que, etc. Tipo: string Valores posibles: `NUM_GTE`, `NUM_GT`, `NUM_EQ`, `NUM_LTE`, `NUM_LT` Valor predeterminado: `NUM_GTE`
negate opcional	Niega el segmento y, por lo tanto, se excluye de la combinación. Tipo: boolean Valor predeterminado: `true` Valores posibles: `true`, `false`

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

    [
      {
        "operation_type":"Crear",
        "params":{
          "name":"mi_audiencia_flexible",
          "audience_type":"FLEXIBLE",
          "segments":{
            "boolean_operator":"Y",
            "child_segments":[
              {
                "custom_audience_id":"TYIF",
                "frequency":1,
                "frequency_comparator":"NUM_GT",
                "lookback_window":30,
                "negate":true,
                "child_segments":[

                ]
              },
              {
                "boolean_operator":"O",
                "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":[

                    ]
                  }
                ]
              }
            ]
          }
        }
      }
    ]

Respuesta de ejemplo

    {
      "data": {
        "targetable": false,
        "name": "mi_audiencia_flexible",
        "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": "mi_audiencia_flexible",
            "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": "mi_audiencia_flexible",
            "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 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 Ads 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 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": "desarrolladores",
        "targetable_types": [
          "CRM",
          "EXCLUDED_CRM"
        ],
        "audience_type": "CRM",
        "description": null,
        "permission_level": "READ_WRITE",
        "owner_account_id": "18ce54d4x5t",
        "id": "2906h",
        "reasons_not_targetable": [
          "DEMASIADO_PEQUEÑO"
        ],
        "created_at": "2017-08-22T23:34:26Z",
        "updated_at": "2017-08-30T18:09:00Z",
        "partner_source": "OTRO",
        "deleted": true,
        "audience_size": null
      },
      "request": {
        "params": {
          "custom_audience_id": "2906h",
          "account_id": "18ce54d4x5t"
        }
      }
    }

Listas de exclusión de contacto

GET accounts/:account_id/do_not_reach_lists

Recupera los detalles de una o todas las Do Not Reach List asociadas con 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 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`
with_deleted optional	Incluye los resultados eliminados en tu solicitud. Type: boolean Default: `false` Possible values: `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": "Lista de no contactar",
          "description": "prueba DNRL",
          "id": "4kzrq",
          "reasons_not_targetable": [
            "DEMASIADO PEQUEÑA"
          ],
          "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 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`
description optional	Descripción de esta audiencia. Type: string Example: `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": "Lista de usuarios a excluir",
          "account_id": "18ce54bgxky"
        }
      },
      "data": {
        "targetable": false,
        "name": "Lista de No Contactar",
        "description": "Lista de usuarios a 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 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 aplicarse como hash usando SHA256 y normalizarse. 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 fijada 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, de forma predeterminada, usa la marca de tiempo actual.
Do Not Reach List 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 publicadas para la cuenta.

Solicitudes por lotes

El tamaño máximo de lote actual 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 sola matriz provoca 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 tienen éxito 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 X Ads API contiene dos campos, success_count y total_count. Estos valores siempre deben ser iguales y representan el conteo 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 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 generalmente es un parámetro obligatorio para todas las solicitudes de la X Ads API, excluyendo GET accounts. La cuenta especificada debe estar asociada con el usuario autenticado. Type: string Example: `18ce54d4x5t`
do_not_reach_list_id required	Referencia a la Do Not Reach List con la que se 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 de un usuario individual. Type: JSON
expires_at optional	La hora UTC a la que debe expirar la(s) asociación(es) del usuario. La hora especificada debe ser posterior al valor de la marca de tiempo actual. Expresado en 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:

Nombre	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 Do Not Reach List 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 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": "Lista de no contactar",
        "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
      }
    }

X Ads API

Fundamentos

Recursos

Medición

​Audiencias Personalizadas

​Descripción general

​Preguntas frecuentes sobre audiencias

​CRM

​Requisitos para la coincidencia de ID de socios

​Requisitos estándar de coincidencia

​Convenciones de nomenclatura y operaciones de archivos de Listas de Segmentos Personalizados

​Creación y actualización de audiencias

​Instrucciones de hashing

​Normalización de correo electrónico

​Normalización de ID de dispositivo

​Normalización del id de usuario de X

​Integración de sincronización de ID

​URL del píxel

​Parámetros de píxel

​Píxel de sincronización de ID:

​Datos de usuario de Custom Audiences

​Audiencias personalizadas: Web

​Integración de la API de Audiences

​Descripción general

​Crear una nueva Audiencia Personalizada

​Agregar usuarios a una audiencia

​Eliminar usuarios de una audiencia

​Usuarios excluidos (opt‑out)

​Referencia de la API

​Información sobre palabras clave

​GET insights/keywords/search

​Permisos de Audiencias a Medida

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

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

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

​Audiencias objetivo

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

​Usuarios de Audiencias personalizadas

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

​URL del recurso

​Parámetros

​Ejemplo de solicitud

​Respuesta de ejemplo

​Permisos de Audiencias Personalizadas

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

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

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

​Audiencias personalizadas

​GET accounts/:account_id/custom_audiences

​GET accounts/:account_id/custom_audiences/:custom_audience_id

​POST accounts/:account_id/custom_audiences

​PUT accounts/:account_id/custom_audiences/:custom_audience_id

​POST batch/accounts/:account_id/custom_audiences

​DELETE accounts/:account_id/custom_audiences/:custom_audience_id

​Listas de exclusión de contacto

​GET accounts/:account_id/do_not_reach_lists

​POST accounts/:account_id/do_not_reach_lists

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

​DELETE accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id

Audiencias Personalizadas

Descripción general

Preguntas frecuentes sobre audiencias

CRM

Requisitos para la coincidencia de ID de socios

Requisitos estándar de coincidencia

Convenciones de nomenclatura y operaciones de archivos de Listas de Segmentos Personalizados

Creación y actualización de audiencias

Instrucciones de hashing

Normalización de correo electrónico

Normalización de ID de dispositivo

Normalización del id de usuario de X

Integración de sincronización de ID

URL del píxel

Parámetros de píxel

Píxel de sincronización de ID:

Datos de usuario de Custom Audiences

Audiencias personalizadas: Web

Integración de la API de Audiences

Descripción general

Crear una nueva Audiencia Personalizada

Agregar usuarios a una audiencia

Eliminar usuarios de una audiencia

Usuarios excluidos (opt‑out)

Referencia de la API

Información sobre palabras clave

GET insights/keywords/search

Permisos de Audiencias a Medida

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

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

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

Audiencias objetivo

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

Usuarios de Audiencias personalizadas

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

URL del recurso

Parámetros

Ejemplo de solicitud

Respuesta de ejemplo

Permisos de Audiencias Personalizadas

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

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

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

Audiencias personalizadas

GET accounts/:account_id/custom_audiences

GET accounts/:account_id/custom_audiences/:custom_audience_id

POST accounts/:account_id/custom_audiences

PUT accounts/:account_id/custom_audiences/:custom_audience_id

POST batch/accounts/:account_id/custom_audiences

DELETE accounts/:account_id/custom_audiences/:custom_audience_id

Listas de exclusión de contacto

GET accounts/:account_id/do_not_reach_lists

POST accounts/:account_id/do_not_reach_lists

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

DELETE accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id