> ## Documentation Index
> Fetch the complete documentation index at: https://generaltranslation.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Audiencias
export const Button = ({href, children}) => {
return
;
};
## Audiencias personalizadas
### Descripción general
Hay varias maneras de que los socios creen [Custom Audiences](https://business.x.com/en/targeting/tailored-audiences.html).
* [Audience API (CRM)](#crm)
* [Web](#web)
* [Móvil](#mobile)
* [Flexible](#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](/es/x-ads-api/audiences)
* [GET accounts/:account\_id/custom\_audiences/:custom\_audience\_id](/es/x-ads-api/audiences)
Para más detalles sobre cómo cargar y gestionar audiencias, consulta la [guía de Audience API](/es/x-ads-api/audiences).
**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](/es/x-ads-api/audiences) 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](/es/x-ads-api/audiences).
**¿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](/es/x-ads-api/measurement/web-conversions#web-event-tags) 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](https://blog.x.com/2014/introducing-tailored-audiences-from-mobile-apps) para más detalles.
**Flexible**
[Flexible audiences](/es/x-ads-api/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](https://developer.x.com/en/developer-terms/more-on-restricted-use-cases "Read more about restrictions")
### Audiences FAQ[](#real-time-tailored-audiences "Permalink to this headline")
**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](/es/x-ads-api/introduction) 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 [mpp-inquiry@x.com](mailto:mpp-inquiry%x.com) 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](http://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/](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: testemail\_Organisational\_baseball+884`@`It92I6Ev2B`.`Com
Después de la normalización: testemail\_organisational\_baseball+884`@`it92i6ev2b`.`com
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](/es/x-ads-api/audiences#crm).
| | |
| :------------ | :--------------------------------------------------- |
| **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:
```json theme={null}
```
**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](/es/x-ads-api/audiences) 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](/es/x-ads-api/audiences). |
**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](/es/x-ads-api/audiences) 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](/es/x-ads-api/audiences).
### 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.: `support@x.com`
**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](https://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](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:///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](/es/x-ads-api/introduction) 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](/es/x-ads-api/audiences).
**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](/es/x-ads-api/audiences).
**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](/es/x-ads-api/audiences). 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](/es/x-ads-api/introduction) 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](/es/x-ads-api/audiences) | Usa `operation` `ADD` con el endpoint [POST custom\_audience\_changes](/es/x-ads-api/audiences) |
| Eliminar un usuario | Usa `operation_type` `Delete` con el [Audience endpoint](/es/x-ads-api/audiences) | Usa `operation` `REMOVE` con el endpoint [POST custom\_audience\_changes](/es/x-ads-api/audiences) |
| Excluir usuarios (opt-out) | Usa `operation_type` `Delete` con el [Audience endpoint](/es/x-ads-api/audiences) y los `custom_audience_id`s correspondientes de los que forma parte el usuario | Usa el [Global opt-out endpoint](/es/x-ads-api/audiences) |
**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](/es/x-ads-api/audiences) y asociada a una Audience usando el endpoint [custom\_audience\_changes](/es/x-ads-api/audiences).
**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](/es/x-ads-api/audiences) 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](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": [
"abc@x.com"
],
"handle": [
"x",
"adsapi"
]
},
{
"email": [
"edf@x.com"
],
"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](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": [
"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 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](https://en.wikipedia.org/wiki/Exponential_backoff) 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[](#get-insights-keywords-search "Enlace permanente a este encabezado")
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[](#resource-url "Enlace permanente a este encabezado")**
`https://ads-api.x.com/12/insights/keywords/search`
**Parámetros[](#parameters "Enlace permanente a este encabezado")**
| 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](https://en.wikipedia.org/wiki/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](https://en.wikipedia.org/wiki/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](/es/x-ads-api/campaign-management#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`).
#### GET accounts/:account\_id/tailored\_audiences/:tailored\_audience\_id/permissions[](#get-accounts-account-id-tailored-audiences-tailored-audience-id-permissions "Permalink to this headline")
Recupera los detalles de algunos o todos los permisos asociados con la audiencia personalizada especificada.
**URL del recurso[](#resource-url "Permalink to this headline")**
`https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions`
**Parámetros[](#parameters "Permalink to this headline")**
| 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](/es/x-ads-api/campaign-management#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](/es/x-ads-api/introduction) 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](/es/x-ads-api/introduction) 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[](#example-request "Permalink to this headline")**
`GET https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/1nmth/permissions`
**Ejemplo de respuesta[](#example-response "Permalink to this headline")**
```
{
"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[](#post-accounts-account-id-tailored-audiences-tailored-audience-id-permissions "Permalink to this headline")
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[](#resource-url "Permalink to this headline")**
`https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions`
**Parámetros[](#parameters "Permalink to this headline")**
| 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](/es/x-ads-api/campaign-management#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[](#example-request "Permalink to this headline")**
`POST https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/2906h/permissions?granted_account_id=18ce54aymz3&permission_level=READ_ONLY`
**Ejemplo de respuesta[](#example-response "Permalink to this headline")**
```
{
"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[](#delete-accounts-account-id-tailored-audiences-tailored-audience-id-permissions-tailored-audience-permission-id "Enlace permanente a este encabezado")
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[](#resource-url "Enlace permanente a este encabezado")**
`https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions/:tailored_audience_permission_id`
**Parameters[](#parameters "Enlace permanente a este encabezado")**
| 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](/es/x-ads-api/campaign-management#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.
#### GET accounts/:account\_id/custom\_audiences/:custom\_audience\_id/targeted[](#get-accounts-account-id-custom-audiences-custom-audience-id-targeted "Enlace permanente a este título")
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](/es/x-ads-api/campaign-management#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](/es/x-ads-api/introduction) para obtener más información.
#### POST accounts/:account\_id/custom\_audiences/:custom\_audience\_id/users[](#post-accounts-account-id-custom-audiences-custom-audience-id-users "Enlace permanente a este encabezado")
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](/es/x-ads-api/audiences#twitter-user-id-normalization).
**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[](#resource-url "Permalink to this headline")
#### Parámetros[](#parameters "Permalink to this headline")
| 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](https://en.wikipedia.org/wiki/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](https://en.wikipedia.org/wiki/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[](#example-request "Enlace permanente a este encabezado")
#### GET accounts/:account\_id/custom\_audiences/:custom\_audience\_id/permissions[](#get-accounts-account-id-custom-audiences-custom-audience-id-permissions "Permalink to this headline")
Recupera los detalles de algunos o todos los permisos asociados con la audiencia personalizada especificada.
**URL del recurso[](#resource-url "Permalink to this headline")**
`https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions`
**Parámetros[](#parameters "Permalink to this headline")**
| 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](/es/x-ads-api/campaign-management#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](/es/x-ads-api/introduction) 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](/es/x-ads-api/fundamentals/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[](#example-request "Permalink to this headline")**
`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/permissions`
**Respuesta de ejemplo[](#example-response "Permalink to this headline")**
```
{
"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[](#post-accounts-account-id-custom-audiences-custom-audience-id-permissions "Permalink to this headline")
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[](#resource-url "Permalink to this headline")**
`https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions`
**Parameters[](#parameters "Permalink to this headline")**
| 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](/es/x-ads-api/campaign-management#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[](#example-request "Permalink to this headline")**
```
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h/permissions?granted_account_id=18ce54aymz3&permission_level=READ_ONLY
```
**Ejemplo de respuesta[](#example-response "Permalink to this headline")**
```
{
"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[](#delete-accounts-account-id-custom-audiences-custom-audience-id-permissions-custom-audience-permission-id "Permalink to this headline")
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[](#resource-url "Permalink to this headline")**
`https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions/:custom_audience_permission_id`
**Parámetros[](#parameters "Permalink to this headline")**
| 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](/es/x-ads-api/campaign-management#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[](#example-request "Permalink to this headline")**
`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/permissions/ri`
**Respuesta de ejemplo[](#example-response "Permalink to this headline")**
```
{
"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[](#get-accounts-account-id-custom-audiences "Enlace permanente a este encabezado")
Obtiene los detalles de algunas o todas las audiencias personalizadas asociadas con la cuenta actual.
**Resource URL[](#resource-url "Enlace permanente a este encabezado")**
`https://ads-api.x.com/12/accounts/:account_id/custom_audiences`
**Parameters[](#parameters "Enlace permanente a este encabezado")**
| 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](/es/x-ads-api/campaign-management#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](/es/x-ads-api/introduction) 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](/es/x-ads-api/fundamentals/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.
#### GET accounts/:account\_id/custom\_audiences/:custom\_audience\_id[](#get-accounts-account-id-custom-audiences-custom-audience-id "Permalink to this headline")
Recupera audiencias personalizadas específicas asociadas a la cuenta actual.
**URL del recurso[](#resource-url "Permalink to this headline")**
`https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id`
**Parámetros[](#parameters "Permalink to this headline")**
| 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](/es/x-ads-api/campaign-management#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.
#### POST accounts/:account\_id/custom\_audiences[](#post-accounts-account-id-custom-audiences "Enlace permanente a este encabezado")
Crea una nueva audiencia personalizada provisional asociada con la cuenta actual.
**URL del recurso[](#resource-url "Enlace permanente a este encabezado")**
`https://ads-api.x.com/12/accounts/:account_id/custom_audiences`
**Parámetros[](#parameters "Enlace permanente a este encabezado")**
| 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](/es/x-ads-api/campaign-management#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[](#example-request "Enlace permanente a este encabezado")**
`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences?name=developers`
**Ejemplo de respuesta[](#example-response "Enlace permanente a este encabezado")**
```
{
"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[](#put-accounts-account-id-custom-audiences-custom-audience-id "Permalink to this headline")
Actualiza la Custom Audience específica asociada con la cuenta actual.
**URL del recurso[](#resource-url "Permalink to this headline")**
`https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id`
**Parámetros[](#parameters "Permalink to this headline")**
| 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](/es/x-ads-api/campaign-management#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[](#example-request "Permalink to this headline")**
`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h?name=developers_changed`
**Ejemplo de respuesta[](#example-response "Permalink to this headline")**
```
{
"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[](#post-batch-accounts-account-id-custom-audiences "Enlace permanente a este encabezado")
Permite la creación por lotes de Audiencias Personalizadas. Consulta la página [Descripción general de las Audiencias Personalizadas](/es/x-ads-api/audiences) 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[](#resource-url "Enlace permanente a este encabezado")**
`https://ads-api.x.com/12/batch/accounts/:account_id/custom_audiences`
**Parameters[](#parameters "Enlace permanente a este encabezado")**
| 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](/es/x-ads-api/campaign-management#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.
#### DELETE accounts/:account\_id/custom\_audiences/:custom\_audience\_id[](#delete-accounts-account-id-custom-audiences-custom-audience-id "Permalink to this headline")
Elimina la audiencia personalizada (Custom Audience) especificada que pertenece a la cuenta actual.
**URL del recurso[](#resource-url "Permalink to this headline")**
`https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id`
**Parámetros[](#parameters "Permalink to this headline")**
| 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](/es/x-ads-api/campaign-management#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.
#### GET accounts/:account\_id/do\_not\_reach\_lists[](#get-accounts-account-id-do-not-reach-lists "Permalink to this headline")
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[](#resource-url "Permalink to this headline")**
`https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists`
**Parameters[](#parameters "Permalink to this headline")**
| 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](/es/x-ads-api/campaign-management#accounts). La cuenta especificada debe estar asociada con el usuario autenticado.
Tipo: string
Ejemplo: `18ce54d4x5t` |
| with\_deleted *optional* | Incluye resultados eliminados en la solicitud.
#### POST accounts/:account\_id/do\_not\_reach\_lists[](#post-accounts-account-id-do-not-reach-lists "Enlace permanente a este encabezado")
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[](#resource-url "Enlace permanente a este encabezado")**
`https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists`
**Parámetros[](#parameters "Enlace permanente a este encabezado")**
| 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](/es/x-ads-api/campaign-management#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[](#example-request "Enlace permanente a este encabezado")**
`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[](#example-response "Enlace permanente a este encabezado")**
```
{
"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[](#post-batch-accounts-account-id-do-not-reach-lists-do-not-reach-list-id-users "Permalink to this headline")
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](/es/x-ads-api/audiences#e-mail-normalization).
**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[](#resource-url "Permalink to this headline")**
`https://ads-api.x.com/12/batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users`
**Parameters[](#parameters "Permalink to this headline")**
| 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](/es/x-ads-api/campaign-management#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](https://en.wikipedia.org/wiki/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.
#### DELETE accounts/:account\_id/do\_not\_reach\_lists/:do\_not\_reach\_list\_id[](#delete-accounts-account-id-do-not-reach-lists-do-not-reach-list-id "Enlace permanente a este encabezado")
Elimina la lista Do Not Reach especificada asociada a la cuenta actual.
**URL del recurso[](#resource-url "Enlace permanente a este encabezado")**
`https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id`
**Parámetros[](#parameters "Enlace permanente a este encabezado")**
Ninguno
**Ejemplo de solicitud[](#example-request "Enlace permanente a este encabezado")**
`DELETE https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists/4ofrp`
**Ejemplo de respuesta[](#example-response "Enlace permanente a este encabezado")**
```
{
"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
}
}
```
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](/es/x-ads-api/audiences).
**¿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](/es/x-ads-api/measurement/web-conversions#web-event-tags) 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](https://blog.x.com/2014/introducing-tailored-audiences-from-mobile-apps) para más detalles.
**Flexible**
[Flexible audiences](/es/x-ads-api/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](https://developer.x.com/en/developer-terms/more-on-restricted-use-cases "Read more about restrictions")
**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](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://