Audiences

Audiences personnalisées

Vue d’ensemble

Il existe plusieurs façons pour les partenaires de créer des Custom Audiences.

Audience API (CRM)
Web
Mobile
Flexible

Veuillez noter que vous ne pouvez pas exclure les custom audiences lookalike du ciblage. De plus, vous ne pouvez pas cibler à la fois une custom audience et une custom audience lookalike dans le même élément de ligne publicitaire (groupe d’annonces). Gestion des audiences Les audiences peuvent être gérées via des partenaires d’audience et des partenaires X Ads API. Nous proposons une série d’endpoints dans l’API pour accéder aux custom audiences et les maintenir. Pour les informations sur les custom audiences, nous proposons 2 endpoints :

Pour plus de détails sur la manière de téléverser et de gérer des audiences, consultez le guide Audience API. Délais de traitement De manière générale, les modifications d’audience sont traitées par lots exécutés toutes les 6 à 8 heures. Pendant le traitement d’une modification, l’audience existante à mettre à jour n’est pas affectée. Nous ne recommandons pas d’effectuer plus d’une mise à jour pour les ajouts et une mise à jour pour les suppressions par audience dans cet intervalle. Ciblage Une audience ne peut être ciblée que si elle correspond à au moins 100 utilisateurs actifs au cours des 90 derniers jours sur les clients détenus et exploités par X. GET accounts/:account_id/custom_audiences/:custom_audience_id indiquera si une audience ne peut pas être ciblée parce qu’elle correspond à un nombre d’utilisateurs insuffisant. Audience API (CRM)

Les partenaires d’audience ou d’API fournissent une liste d’identifiants hachés, X effectue la mise en correspondance et produit des segments disponibles pour l’achat média sur X. Les partenaires peuvent créer ces audiences avec l’Audience API. Comment cela fonctionne-t-il ?

Web Nous proposons un processus standard d’appariement de cookies lors de la collaboration avec des partenaires d’audience MPP pour identifier des segments à cibler pour l’achat média sur X. En outre, les annonceurs peuvent configurer une balise d’événement Web X pour collecter les données des utilisateurs du site web et créer une Custom Audience correspondante. Étapes de configuration

Comment cela fonctionne-t-il ?

Mobile Veuillez consulter l’article de blog « Custom Audiences from Mobile Apps » pour plus de détails. Flexible Les Flexible audiences donnent aux annonceurs la possibilité de créer et d’enregistrer des combinaisons d’audiences basées sur des custom audiences existantes ou des sous-ensembles de custom audiences existantes. Des sous-ensembles des membres d’une custom audience peuvent être ciblés en fonction de la récence et de la fréquence d’interaction. Cas d’utilisation restreints pour les Custom Audiences En savoir plus sur les restrictions

FAQ sur les audiences

Q : Nous avons envoyé une grande quantité de données ; pourquoi la taille de l’audience s’affiche-t-elle comme TOO_SMALL ? R : Actuellement, les données sont ajoutées à l’audience en temps réel, mais la tâche qui traite les données pour calculer la taille de l’audience ne s’exécute qu’après un certain délai. La taille correcte de l’audience devrait s’afficher dans l’interface après quelques heures. Q : Nous avons fini d’envoyer les données d’audience et attendu 24 heures ou plus, mais nous ne pouvons toujours pas cibler l’audience – quelles sont les prochaines étapes ? R : Veuillez confirmer les éléments suivants :

L’id utilisateur transmis est correct et non mal formé.
Les noms d’audience transmis sont corrects et correspondent aux mises à jour d’appartenance précédentes.
Veuillez confirmer la réponse des commandes POST.
Veuillez confirmer que le pixel ID Sync est correctement implémenté et, comme décrit par le processus ID Sync, qu’un nombre suffisant d’utilisateurs ont visité le site en question pour établir la correspondance. Les utilisateurs non appariés dans les mises à jour d’appartenance ne seront pas convertis en utilisateurs ciblés.

Si tout le reste est confirmé comme correct et fonctionnel, veuillez contacter vos interlocuteurs produit X avec des informations aussi détaillées que possible (voir Guide to Partner Inbounds pour un exemple d’informations attendues). Q : Combien de fois pouvons-nous appeler l’endpoint, et avec quel algorithme ? R : Nous recommandons vivement d’appeler notre système avec des deltas incrémentaux et de ne jamais renvoyer l’intégralité des appartenances d’audience. Le système a été testé pour un débit suffisant afin de traiter des mises à jour de données incrémentielles pour certains des plus grands sites web au monde. Le chargement initial des audiences doit être soigneusement limité, et le premier envoi devrait prendre un temps significatif. Q : Quelle est la taille minimale d’une audience pour être utilisée pour le ciblage ?

La taille minimale d’une audience est de 100 utilisateurs (après correspondance). Si une audience de moins de 500 utilisateurs est appariée, elle ne sera pas disponible pour le ciblage dans l’interface X Ads.

Q : Combien de temps faut-il pour traiter les fichiers d’audience ? Et combien de temps avant qu’ils soient prêts dans l’interface X ?

Le traitement des fichiers d’audience prend généralement 4 à 6 heures, mais cela dépend de la taille du fichier. Une fois le fichier traité, les audiences sont disponibles dans l’interface X Ads.

Q : Comment le taux de correspondance est-il calculé ?

Taux de correspondance = utilisateurs X actifs sur 90 jours / nombre d’utilisateurs fournis

Q : Comment tester si un fichier d’audience fonctionne correctement ?

Vous pouvez fournir un fichier d’audience de test et utiliser « keltonlynn » comme handle annonceur. Nous pourrons alors vérifier que le fichier peut être correctement ingéré et chargé dans l’interface X.

Q : Qu’est-ce qu’un identifiant utilisateur partenaire (p_user_id) ?

Il s’agit de l’identifiant utilisé par votre entreprise pour identifier de manière unique chacun de vos clients.

Q : Qu’est-ce qu’un ID standard ?

Il peut s’agir d’une adresse e‑mail, d’un ID d’appareil, d’un @handle X ou d’un ID.

Q : Comment obtenir la clé HMAC ?

Elle sera fournie par e‑mail chiffré. Veuillez fournir votre clé PGP publique à mpp-inquiry@x.com et nous vous enverrons un e‑mail de test pour vérifier que tout fonctionne. Une fois vérifié, nous vous enverrons la clé HMAC.

Q : Comment vérifier que le processus de hachage a fonctionné avec la clé HMAC fournie ?

X fournira un fichier de test (contenant des adresses e‑mail d’exemple, des ID d’appareil, etc.) et un fichier de hash résultant contre lequel vous pourrez comparer vos résultats.

Q : Y a-t-il une limite de taille pour le fichier de correspondance complète des données ?

Non, il n’y a pas de limite de taille pour le fichier de correspondance complète des données.

Q : Combien de temps faudra-t-il pour traiter le fichier de correspondance complète des données ?

Une fois le fichier reçu par X, le traitement prendra environ 1 jour.

CRM

Ce document décrit les détails d’intégration pour les partenaires CRM de Custom Audiences, notamment les formats de fichiers et le processus d’échange de données. Résumé L’entreprise fournira, au nom d’un client, une liste d’identifiants utilisateur courants hachés (p. ex. adresses e‑mail) ou des id utilisateur du partenaire à X afin d’effectuer une correspondance à l’aveugle et de produire une liste d’id d’utilisateurs X pour le ciblage. Les segments de ciblage seront mis à la disposition du @handle spécifique de l’annonceur, indiqué par le nom de fichier lors de la configuration de la campagne sur ads.x.com. Tous les fichiers provenant de l’entreprise seront transmis à X via un paquet sécurisé sur IronBox (www.golockbox.com) au moyen d’un compte spécifique accordé à l’entreprise par X. X fournira l’accès à IronBox. La documentation sur les API IronBox est disponible à l’adresse https://secure.goironcloud.com/Docs/Help/.

Exigences de correspondance des ID partenaire

Si l’entreprise utilise son propre système d’ID standard pour suivre les utilisateurs (c.-à-d. pas des identifiants courants comme les adresses e‑mail, les id d’appareil, l’ID utilisateur X, etc.), le processus recommandé est le suivant. 1. Correspondance complète des données Au départ, l’entreprise fournira, dans un fichier unique, une liste exhaustive de tous les enregistrements utilisateurs incluant un identifiant utilisateur courant unique partagé avec X, afin d’effectuer une correspondance complète des données et de produire un mappage, stocké par X, des ID partenaire (p_user_id) vers les ID X (tw_id). Cette opération sera réalisée régulièrement, tous les 2 à 3 mois, pour en assurer la bonne tenue. Une fois la correspondance effectuée, X communiquera par e‑mail à l’entreprise un taux de correspondance de référence issu de ce fichier. Le format de ce fichier doit être : Convention de nommage : FullDataMatch.[CompanyName].txt Algorithme de hachage : HMAC_SHA-256 Format : Colonne 1 : valeur hachée HMAC des identifiants courants Colonne 2 : ID utilisateur partenaire (unique par utilisateur, non unique dans le fichier) Délimiteur de colonnes (CSV) : des virgules seront utilisées pour séparer l’identifiant utilisateur courant haché de l’ID partenaire Valeurs séparées par des sauts de ligne

Ex. : si l’enregistrement utilisateur A a l’ID utilisateur partenaire 1 et les identifiants courants 1, 2 et 3 :


identifiant utilisateur courant 1	p_user_1
identifiant utilisateur courant 2	p_user_1
identifiant utilisateur courant 3	p_user_1

*Voir la section Directives de hachage ci‑dessous pour les identifiants utilisateur courants 2. Listes de segments personnalisés L’entreprise fournira des listes d’utilisateurs sous la forme de p_user_id pour créer des audiences personnalisées destinées au ciblage sur X.

Valeurs séparées par des sauts de ligne
p_user_id
- (Identique à la section 1. Correspondance complète des données ci‑dessus. Si la valeur fournie dans la correspondance complète est hachée, l’entreprise fournira la même valeur hachée dans le fichier d’audience. Si la valeur fournie n’est pas hachée, l’entreprise fournira la valeur en clair.)

Exigences de correspondance standard

Si l’entreprise n’utilise pas un identifiant standard pour la mise en correspondance de tous les identifiants utilisateur de clients, voici le processus recommandé. Listes de segments personnalisés L’entreprise fournira directement à X, au nom des clients, des listes d’identifiants utilisateur courants hachés afin de créer des audiences personnalisées. Le format de ce fichier doit être :

Valeurs séparées par des lignes
Identifiant utilisateur courant haché (p. ex., adresse e‑mail)
Respecter les conventions de dénomination des fichiers décrites ci‑dessous
Suivre les instructions de hachage pour les adresses e‑mail ci‑dessous (voir Instructions de hachage)

Nommage et opérations des fichiers de segment personnalisé

Le comportement d’un fichier est déterminé par son nom, selon les opérations disponibles ci-dessous et la convention générale de nommage : audiencename_partnername.handle.operation.filetype

audiencename : Nom de la Custom Audience. Ce champ est le nom affiché lors de la sélection de l’audience dans l’interface de configuration des campagnes sur ads.x.com, par exemple brand_loyalty_card_holders.
partnername : Nom de l’entreprise fournissant les données au nom de l’annonceur, par exemple company_name.
handle : Compte X (@handle) qui aura accès aux Custom Audiences, par exemple @pepsi, @dietpepsi
operation : new, add, remove, removeall, replace (détails ci-dessous)
: Horodatage Unix (epoch) standard en secondes, utilisé pour garantir l’unicité de chaque fichier d’audience téléversé
filetype : le fichier doit être au format *.txt

Création et mise à jour des audiences

Créez une nouvelle audience avec un seul fichier, par exemple loyalty_card_holders_partnername.pepsi.new.txt Ajouter - Ajouter les correspondances d’une liste à une audience existante, par exemple loyalty_card_holders_partnername.pepsi.add..txt Remove - Supprimer les correspondances d’une liste d’une audience existante. Ex. : loyalty_card_holders_partnername.pepsi.remove..txt Remove All - Supprimer de toutes les audiences de ce client les correspondances issues d’une liste cumulative régulièrement mise à jour (c.-à-d. la liste d’exclusion du client). Ex. : partnername.pepsi.removeall.txt

Peut être utilisé pour une liste complète d’utilisateurs s’étant désinscrits de l’annonceur.
X ne prendra en compte que la dernière liste fournie dans ce fichier et l’appliquera à toutes les audiences existantes et futures pour les correspondances d’utilisateurs X au moment où ce fichier a été fourni et traité.

Replace - Supprimer une audience existante et la remplacer par une nouvelle liste d’audience. Ex. : loyalty_card_holders_partnername.pepsi.replace..txt Désinscription globale de l’entreprise - L’entreprise fournira un fichier cumulatif de désinscription pour supprimer les utilisateurs qui se sont désinscrits conformément à la politique de désinscription de l’entreprise. X ne prendra en compte que la dernière liste fournie dans ce fichier de désinscription de l’entreprise et l’appliquera à toutes les audiences existantes et futures pour les utilisateurs X correspondants au moment où ce fichier a été fourni et traité. Le format du fichier de désinscription de l’entreprise sera le suivant : Ex. : partnername.removeall.txt Delete - Supprimer une audience existante de la liste actuelle des audiences, par ex. : loyalty_card_holders_partnername.pepsi.delete.txt

Directives de hachage

X partagera en toute sécurité, via PGP, une clé de production encodée en base64 pour le hachage des identifiants utilisateur courants (par ex. les adresses e‑mail). L’entreprise décodera la clé en base64 pour obtenir une clé de 32 octets à utiliser pour le hachage. Exemple de clé encodée en base64 : BrQvOg+dACBUmKjRiNxZgJLh6zydjS0ZOv80FelTNzM= Exemple de clé décodée en base64 : /:� TшY Normalisation : l’entreprise appliquera une normalisation de base aux identifiants utilisateur courants avant le hachage (à l’exception des Device IDs, voir la section Normalisation des Device IDs).

Normalisation de l’e-mail

Concrètement, supprimez les espaces en début et en fin, puis mettez l’adresse e‑mail en minuscules. Ex. : adresse e‑mail brute : testemail_Organisational_baseball+884@It92I6Ev2B.Com Après normalisation : testemail_organisational_baseball+884@it92i6ev2b.com Valeur de hash : 74d9584eded0ad1e5572a1c1849f3716751d371d6117a6155dad5363f4b4fbec Remarque : Le nombre de caractères du hmac encodé et de la clé peut varier selon l’entrée et l’encodage ; il n’est donc pas fixe.

Normalisation des identifiants d’appareil

Nous appliquerons les mêmes exigences pour le hachage des identifiants d’appareil à l’aide de l’algorithme SHA‑256 et d’un sel commun que nous fournissons aux partenaires de données. Nous supprimons les espaces, comme pour les adresses e‑mail, mais il n’y a pas de conversion en minuscules pour les IDFA/ID Android et il faut utiliser le format exact de l’IDFA/ID Android. Voici un exemple de format brut des identifiants d’appareil pour iOS et Android, avant hachage : IDFA iOS : DD99CFF7-6186-4602-9DF2-ED3FD0B2D431 ID Android : b5bf2122961b3595 IDFA iOS haché : 134fb8cd95c7fd42e2793f469a447198ca5f990968db2dbadad70e723ed9750b ID Android haché : 130dddff1939f229476f50bc8adab8fcb7e3525b0e9604fe8effc15e68cee4a4

Normalisation des identifiants utilisateur X

Les identifiants X seront toujours hachés, car le regroupement des data — c’est‑à‑dire une Customer List de @handles — est privé pour l’annonceur, même s’il ne s’agit pas de PII. Nous appliquerons les mêmes exigences de hachage des identifiants X à l’aide de l’algorithme SHA‑256 et d’un sel commun que nous fournissons aux partenaires data. Les espaces doivent être supprimés à la fois dans l’identifiant X et le @username, mais les User IDs ne nécessitent pas de normalisation. Les @usernames doivent être convertis en minuscules pour la normalisation. Le symbole @ ne doit pas être inclus dans le nom d’utilisateur. Le format brut de l’identifiant sera :

User ID: 27674040
@username: testusername

Hashed User ID: bf6b57d4e861e83bea8bbed2b800b251a64c95468ee6e8cb07c3368c9ed45e85 Hashed @username: 12201ae78ad1afa907c7112d17f498154ffb0bf9ea523f5390e072a06d7d9812

Intégration de synchronisation d’ID

Les partenaires qui envoient des data avec un p_id doivent effectuer un processus de synchronisation d’ID afin de générer un mappage entre les id utilisateur de l’annonceur ou du partenaire et les id utilisateur X. Cela permet aux annonceurs de cibler directement leurs propres segments d’utilisateurs sur X. Les partenaires doivent également définir la valeur du paramètre user_identifier_type sur TALIST_PARTNER_USER_ID ou TAWEB_PARTNER_USER_ID lors de l’envoi de leurs mises à jour de membres.

Web uniquement : Cela peut être réalisé en plaçant un pixel sur le site de l’annonceur, comme indiqué ci-dessous.
List : Cela peut être réalisé en utilisant l’une des méthodes décrites sur la page CRM.

URL du pixel


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

Paramètres du pixel


Paramètre	Description
`p_id`	Votre id de partenaire attribué par X
`p_user_id`	L’id de l’utilisateur dans le système du partenaire

Pixel de synchronisation d’ID :

En prenant un id de partenaire d’exemple 111 et un p_user_id d’exemple abc, le pixel construit serait le suivant :

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

Configuration du fichier de désinscription et envoi des fichiers de désinscription Les partenaires doivent fournir à X une liste d’utilisateurs qui, au meilleur de leur connaissance, ont choisi de se désinscrire de la diffusion d’annonces ciblées. Le format du fichier doit être le suivant :


Numéro de colonne	Nom de la colonne	Type de colonne	Description
1	Partner ID	string	Le « partner id » est l’identifiant que X fournit au partenaire afin d’identifier de manière unique chaque partenaire.
2	id de l’utilisateur dans le système du partenaire	string	Le `p_user_id` est l’identifiant unique utilisé par le partenaire pour identifier l’utilisateur. Le fichier contenant ces utilisateurs désinscrits doit être importé via l’endpoint TON upload et le chemin des data importées doit être envoyé à l’endpoint Global Opt Out ici : PUT accounts/:account_id/custom_audiences/global_opt_out.

Envoi des mises à jour d’appartenance Comme spécifié dans notre documentation d’endpoint, lors de l’envoi d’utilisateurs via l’endpoint POST custom_audience_memberships, vous devez transmettre un ID client pour activer une correspondance basée sur les cookies. Les partenaires envoyant des data avec un p_id doivent définir user_identifier_type sur TALIST_PARTNER_USER_ID ou TAWEB_PARTNER_USER_ID. Toutes les autres étapes resteront identiques à celles décrites dans le Guide d’intégration de l’API Real-Time Audience

Données utilisateur pour Custom Audiences

Ce document décrit le format des données utilisateur pour [Custom Audience]/x-ads-api/audiences. Normalisation des données Identifiants d’appareil :

IDFA - en minuscules avec des tirets ; ex. : 4b61639e-47cc-4056-a16a-c8217e029462
AdID - le format d’origine sur l’appareil est requis, non capitalisé avec des tirets ; ex. : 2f5f5391-3e45-4d02-b645-4575a08f86e
Android id - le format d’origine sur l’appareil est requis, non capitalisé, sans tirets ni espaces ; ex. : af3802a465767e36

Adresses e-mail :

en minuscules, supprimer les espaces en début et en fin ; ex. : support@x.com

Noms d’utilisateur X :

sans @, en minuscules et avec suppression des espaces en début et en fin ; ex. : jack

Identifiants utilisateur X :

Entier standard ; ex. : 143567

Hachage des données Les données de chaque ligne doivent être hachées à l’aide de SHA256, sans sel. De plus, le hash final en sortie doit être en minuscules. Par exemple, 49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d et non 49E0BE2AECCFB51A8DEE4C945C8A70A9AC500CF6F5CB08112575F74DB9B1470D

# hachage de l'utilisateur @AdsAPI avec python
import hashlib
hashlib.sha256("adsapi".encode()).hexdigest()

#sortie
49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d

Des exemples de code supplémentaires pour le hash sont disponibles sur github.com/xdevplatform/ads-platform-tools.

Audiences personnalisées : Web

Informations Les partenaires enverront une liste d’id (p_user_ids) à cibler pour le compte d’un annonceur. Cela se fait via un processus de synchronisation d’id qui établit une correspondance entre les p_user_ids et l’id utilisateur X. Cette correspondance est ensuite utilisée pour produire des listes d’id d’utilisateurs X utilisables pour le ciblage. Ces audiences personnalisées seront mises à disposition sur le @handle spécifique de l’annonceur, tel qu’indiqué par le libellé dans la configuration de la campagne Custom Audiences Web sur ads.x.com. X fournira le pixel sécurisé qui pourra être intégré aux tags et aux sites du partenaire afin d’associer les id (p_user_ids) aux id d’utilisateurs X. Une fois le processus de synchronisation d’id terminé, les fichiers de ciblage seront créés par le partenaire et mis à disposition de X via un endpoint HTTPS. Ces fichiers de ciblage sont régulièrement ingérés par X, puis rendus disponibles dans l’interface X. Pixel sécurisé X Le pixel sécurisé X se présentera comme suit : https://analytics.x.com/i/adsct?p_user_id=xyz&p_id=123 p_user_id - xyz représente l’id utilisateur du partenaire fourni par le partenaire p_id - 123 représente l’id unique du partenaire (fourni par X) Endpoint HTTPS du partenaire & fichier d’utilisateurs pour le ciblage Le partenaire devra fournir à X un endpoint HTTPS et des identifiants (nom d’utilisateur/mot de passe) permettant d’ingérer le fichier de ciblage à intervalles réguliers. Un exemple d’endpoint HTTPS se présentera comme suit :

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

%Y - Code de format pour l’année (YYYY) %M - Code de format pour le mois (MM) %D - Code de format pour le jour (DD) Les données transmises seront composées des fichiers suivants :

Fichier des utilisateurs de ciblage du partenaire
Fichier de conversion de ciblage

Tous les fichiers seront au format TSV, où les fields individuels de chaque ligne sont séparés les uns des autres par un caractère de tabulation. Les valeurs de field valides ne contiendront jamais le caractère de tabulation. Plage d’IP X autorisée : Voici la plage d’IP pouvant être autorisée pour accéder à l’endpoint partenaire.

199.16.156.0/22
199.59.148.0/22

Fichier des utilisateurs de ciblage du partenaire :

Numéro de colonne	Nom de colonne	Type de colonne	Description
1	partner id	string	Le « partner id » est l’id que X fournit au partenaire afin d’identifier de manière unique chaque partenaire.
2	advertiser id	string	Le « advertiser id » est le @handle de l’annonceur.
3	p_user_id	string	Le « p_user_id » est l’id unique utilisé par le partenaire pour identifier l’utilisateur.
3	confidence score	integer	Le « confidence score » est facultatif. Nous recommandons d’utiliser une plage de 0 à 100. Si le cas d’usage est le reciblage, un « 100 » désigne un utilisateur directement reciblé. Tout score de 0 à 99 correspond au niveau de confiance du profil similaire (look-alike).
4	segment label	string	Le « segment label » est facultatif. Les partenaires peuvent utiliser « segment label » pour spécifier, par exemple, des catégories de produits. Nous recommandons d’utiliser ce « segment label », car c’est le nom lisible pour les audiences personnalisées (Custom Audiences) dans l’interface ads.x.com.

Notes : Chaque fois que nous recevons un nouveau fichier de ciblage du partenaire, nous nous attendons à ce qu’il s’agisse de la liste complète des utilisateurs que le partenaire nous recommande de cibler, et non d’un incrément, sauf accord contraire. Nous conviendrons avec chaque partenaire de la fréquence de livraison de ce fichier de ciblage du partenaire. Si nous ne recevons pas un fichier de ciblage du partenaire comme prévu, nous utiliserons la version précédente avec un délai d’expiration prédéfini.

Intégration de l’API Audience

Présentation

L’Audience API a été lancée dans le cadre de v4 de la X Ads API et apporte plusieurs améliorations par rapport aux endpoints Audiences hérités. Ce nouvel endpoint s’appuie sur un nouveau backend de traitement des Audiences et offre plusieurs améliorations en termes de stabilité, de robustesse et de fiabilité. L’objectif de ce guide est de mettre en évidence les différences entre l’Audience API et les anciens processus de chargement et de gestion des Audiences. La documentation de référence est disponible sur la page de référence de l’Audience API. Remarque : Toutes les données utilisateur d’Audience doivent être hachées avec SHA‑256 avant le chargement. Plus de détails, ainsi que les types d’identifiants utilisateur acceptés et la normalisation des données, sont disponibles sur la page user data. Modifications de la fonctionnalité Audience Les changements suivants concernant les Custom Audiences ont été introduits à partir de la v4 et tout endpoint obsolète ne sera plus disponible une fois la v3 de la X Ads API retirée :

Obsolète Téléversement TON :
- 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
Obsolète Real Time Audiences :
- POST custom_audience_memberships
Custom Audience :
- Le paramètre list_type sera supprimé de la requête et de la réponse sur tous les endpoints Custom Audience. Ce paramètre servait auparavant à identifier le type d’identifiant utilisateur de l’Audience (p. ex., email, X User ID, etc.) ; toutefois, les Audiences peuvent désormais accepter plusieurs identifiants utilisateur pour une même Audience, rendant cette valeur caduque.
Général :
- La fenêtre de rétroactivité de l’Audience a été mise à jour pour correspondre aux utilisateurs actifs au cours des 90 derniers jours (contre 30 jours auparavant)
- Le nombre minimal d’utilisateurs correspondants requis pour qu’une audience soit ciblable a été réduit à 100 utilisateurs (contre 500 auparavant)

Prérequis

Accès à la X Ads API
Pour accéder à l’endpoint Audience, vous devrez être ajouté à une allowlist. Veuillez remplir ce formulaire et accepter le nouveau X Ads Products and Services Agreement si l’acceptation initiale est antérieure au 2018-08-01

Processus de chargement d’Audience Le tableau suivant répertorie les principales différences entre les anciens et les nouveaux flux de création d’Audience, avec davantage de détails plus bas :

Étape du processus	Audience API	Téléversement TON (obsolète)
Créer une Audience de base	Peut être créée via le [POST custom_audience endpoint]/x-ads-api/audiences	Peut être créée via le [POST custom_audience endpoint]/x-ads-api/audiences
Ajouter un nouvel utilisateur	Utiliser `operation_type` `Update` avec l’Audience endpoint	Utiliser `operation` `ADD` avec l’endpoint POST custom_audience_changes
Supprimer un utilisateur	Utiliser `operation_type` `Delete` avec l’Audience endpoint	Utiliser `operation` `REMOVE` avec l’endpoint POST custom_audience_changes
Désinscription des utilisateurs (opt-out)	Utiliser `operation_type` `Delete` avec l’Audience endpoint et les `custom_audience_id` correspondants dont l’utilisateur fait partie	Utiliser l’endpoint Global opt-out

Remarque Toute audience mise à jour ou désinscrite via le chemin de téléversement TON doit avoir une liste correspondante chargée via l’endpoint TON Upload et associée à une Audience à l’aide de l’endpoint custom_audience_changes. Limitation de taux L’endpoint Audience API a une limite de taux de 1500/1 min par compte. Il n’y a aucune limite quant au nombre d’utilisateurs pouvant être envoyés dans une seule charge utile. Les seules contraintes sur la charge utile sont :

Nombre total d’opérations : 2500 opérations
Taille maximale de la charge utile : 5 000 000 octets

Gestion des utilisateurs d’Audience Pour créer une nouvelle Audience, les étapes suivantes sont requises

Créer une nouvelle Audience personnalisée

Créez un nouveau « conteneur » d’Audience personnalisée à l’aide de l’endpoint [POST custom_audience]/x-ads-api/audiences et récupérez l’id de l’Audience personnalisée correspondant. Cette étape est requise si vous créez une Audience à partir de zéro. Si vous mettez à jour une Audience existante, passez à la section suivante.

Ajouter des utilisateurs à une Audience

Utilisez POST accounts/:account_id/custom_audiences/:custom_audience_id/users avec l’id de la Custom Audience et un exemple de payload comme suit : POST https://ads-api.x.com/11/accounts/18ce54d4x5t/custom_audiences/1nmth/users

    # Toutes les valeurs doivent être hachées, les valeurs non hachées sont utilisées dans cet exemple à des fins d'illustration
    [
      {
        "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"
              ]
            }
          ]
        }
      }
    ]

Pour ajouter un utilisateur à une Audience, utilisez operation_type Update. La nouvelle interface Audience permet de transmettre plusieurs clés d’utilisateur pour un même utilisateur. Chaque objet du tableau d’objets JSON correspond à un utilisateur. En reprenant l’exemple de payload ci-dessus, la requête ajoutera deux utilisateurs à une Audience, l’un avec un email et un handle, et l’autre avec un email et un twitter_id.

Supprimer des utilisateurs d’une audience

Comme pour l’ajout d’utilisateurs, vous pouvez supprimer des utilisateurs d’une audience comme suit : POST https://ads-api.x.com/11/accounts/18ce54d4x5t/custom_audiences/1nmth/users

    # Toutes les valeurs doivent être hachées, les valeurs non hachées sont utilisées dans cet exemple à des fins d'illustration
    [
      {
        "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"
              ]
            }
          ]
        }
      }
    ]

Le champ operation_type doit être défini sur Delete, et les utilisateurs seront mis en correspondance selon n’importe laquelle des clés fournies lors de leur ajout à l’audience. Par exemple, si un utilisateur a été ajouté à une audience avec un email et un twitter_id, ce même utilisateur peut ensuite être supprimé en utilisant l’une de ces clés (soit email, soit twitter_id), ou les deux. Il est également possible d’ajouter et de supprimer des utilisateurs d’une audience dans une même requête. L’endpoint prend en charge plusieurs valeurs de operation_type par requête.

Utilisateurs en désinscription (opt-out)

Avec l’abandon de l’endpoint d’opt-out global, les partenaires doivent effectuer une opération DELETE pour tout utilisateur qui s’est désinscrit de toute Audience. Plusieurs approches sont possibles :

Suivre quels utilisateurs appartiennent à quelles Audiences et retirer ces utilisateurs individuellement de chaque Audience.
Retirer l’utilisateur de toutes les Audiences associées à un compte Ads.

Bonnes pratiques générales

Nous recommandons vivement d’appeler cet endpoint par lots quasi en temps réel afin d’éviter des files d’attente en dents de scie, plus longues à traiter et générant une charge inutile sur notre système. Cela garantit également que les utilisateurs sont disponibles plus rapidement pour le ciblage des campagnes.
Un appel à l’API réussi renverra un success_count et un total_count correspondant au nombre d’objets user reçus dans la requête.
Cet endpoint est atomique : soit l’ensemble de la requête réussit, soit, en cas d’erreur, l’intégralité de la requête échoue. En cas de réponse d’erreur, il est recommandé aux consommateurs de l’API de corriger le problème et de réessayer la requête avec l’intégralité de la charge utile.
En cas d’échec, il est recommandé aux partenaires d’utiliser une stratégie de retrait exponentiel avec des tentatives de nouvelle exécution. Par exemple : réessayez immédiatement lors du premier échec, réessayez après 1 minute après le deuxième échec, puis après 5 minutes après le troisième échec consécutif, et ainsi de suite.

Référence de l’API

Informations sur les mots-clés

GET insights/keywords/search

Pour un groupe de mots-clés donné, récupérez le volume de Tweets associé ainsi qu’un ensemble de 30 mots-clés liés. Le volume de Tweets correspond uniquement aux mots-clés fournis en entrée, pas aux mots-clés liés. Un intervalle de temps maximal (end_time - start_time) de 7 jours est autorisé. Veuillez noter que les résultats sont limités à une seule zone géographique (pays). Resource URL https://ads-api.x.com/12/insights/keywords/search Parameters

Name	Description
granularity required	Spécifie la granularité des données renvoyées pour l’intervalle temporel défini par `start_time` et `end_time`. Par exemple, lorsque la valeur est `HOUR`, un point de données est fourni pour chaque heure entre `start_time` et `end_time`. Type: enum Valeurs possibles : `DAY`, `HOUR`
keywords required	Une chaîne de mots-clés séparés par des virgules pour affiner la recherche. Tous les mots-clés sont reliés par un OU logique entre eux. Remarque : Un maximum de 10 mots-clés (combinaison de `keywords` et `negative_keywords`) peut être utilisé. Type: string Exemple : `developers`
start_time required	Limite les données renvoyées à celles collectées dans la fenêtre de temps entre `start_time` et `end_time`. Exprimé en ISO 8601. Type: string Exemple : `2017-07-10T00:00:00Z`
end_time optional	Limite les données renvoyées à celles collectées dans la fenêtre de temps entre `start_time` et `end_time`. Exprimé en ISO 8601. Remarque : Par défaut, l’heure actuelle est utilisée. Type: string Exemple : `2017-07-11T00:00:00Z`
location optional	Une valeur de ciblage obtenue via l’endpoint GET targeting_criteria/locations pour affiner les résultats en fonction de l’emplacement de l’utilisateur du compte. Notez qu’à l’heure actuelle, seuls les emplacements au niveau pays sont pris en charge. Type: string Exemple : `0ce8b9a7b2742f7e`
negative_keywords optional	Une chaîne de mots-clés séparés par des virgules à exclure. Tous les mots-clés négatifs sont reliés par un OU logique entre eux. Remarque : Un maximum de 10 mots-clés (combinaison de `keywords` et `negative_keywords`) peut être utilisé. Type: string Exemple : `rain`

Example Request

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

Exemple de réponse*

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

Autorisations pour les audiences personnalisées

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

Récupère les détails de certaines ou de toutes les autorisations associées à l’audience personnalisée spécifiée. Resource URL https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions Parameters

Name	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: `18ce54d4x5t`
tailored_audience_id required	Référence de l’audience personnalisée concernée par la requête. Type: string Example: `1nmth`
count optional	Spécifie le nombre d’enregistrements à tenter de récupérer par requête. Type: int Default: `200` Min, Max: `1`, `1000`
cursor optional	Spécifie un curseur pour obtenir la page de résultats suivante. Voir Pagination pour plus d’informations. Type: string Example: `8x7v00oow`
granted_account_ids optional	Restreint la réponse aux comptes souhaités en spécifiant une liste d’identifiants séparés par des virgules. Jusqu’à 200 id peuvent être fournis. Type: string Example: `18ce54aymz3`
sort_by optional	Trie selon un attribut pris en charge, par ordre croissant ou décroissant. Voir Sorting pour plus d’informations. Type: string Example: `created_at-asc`
tailored_audience_permission_ids optional	Restreint la réponse aux autorisations d’audience personnalisée souhaitées en spécifiant une liste d’identifiants séparés par des virgules. Jusqu’à 200 id peuvent être fournis. Type: string Example: `ri`
with_total_count optional	Inclut l’attribut de réponse `total_count`. Remarque : ce paramètre et `cursor` s’excluent mutuellement. Remarque : les requêtes incluant `total_count` sont soumises à des limites de taux plus faibles, actuellement fixées à 200 par 15 minutes. Type: boolean Default: `false` Possible values: `true`, `false`

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

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

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

Crée un nouvel objet d’autorisation permettant de partager l’audience spécifiée avec un compte donné. Remarque : La création ou la modification d’autorisations pour une audience personnalisée exige que l’audience appartienne au compte qui tente de modifier les autorisations. Vous pouvez vérifier la propriété d’une audience personnalisée en consultant l’attribut de réponse is_owner dans la réponse pour l’audience concernée. Remarque : Les audiences ne peuvent être partagées qu’entre des comptes publicitaires d’une même entreprise ou si le compte publicitaire propriétaire de l’audience dispose de la fonctionnalité de compte SHARE_AUDIENCE_OUTSIDE_BUSINESS. Resource URL https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions Parameters

Name	Description
account_id required	L’identifiant du compte exploité. Apparaît dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : `18ce54d4x5t`
granted_account_id required	Le compte auquel vous souhaitez accorder des autorisations pour l’audience personnalisée. Type : string Exemple : `18ce54aymz3`
permission_level required	Le type d’accès à l’audience personnalisée que `granted_account_id` doit avoir. Type : enum Valeurs possibles : `READ_ONLY`, `READ_WRITE`
tailored_audience_id required	La référence de l’audience personnalisée visée par la requête. Type : string Exemple : `2906h`

Example Request

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

Example Response

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

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

Révoque l’autorisation de partage de l’audience personnalisée spécifiée. Remarque : La création ou la modification d’autorisations pour une audience personnalisée nécessite que l’audience soit détenue par le compte qui tente de modifier les autorisations. Vous pouvez vérifier la propriété d’une audience personnalisée en consultant l’attribut de réponse is_owner dans la réponse pour l’audience concernée. Une fois révoquée, nous garantissons que le compte destinataire (granted_account_id) ne pourra pas cibler l’audience dans de futures campagnes. Les campagnes existantes continueront de s’exécuter avec les audiences partagées ; les campagnes ne s’arrêtent pas et l’audience n’est pas retirée de la campagne. Il n’est pas possible de copier cette campagne après la révocation de l’autorisation de partage de l’audience. Resource URL

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

Parameters

Nom	Description
account_id obligatoire	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : `18ce54d4x5t`
tailored_audience_id obligatoire	Référence à l’audience personnalisée utilisée dans la requête. Type : string Exemple : `1nmth`
tailored_audience_permission_id obligatoire	Référence à l’autorisation d’audience personnalisée utilisée dans la requête. Type : string Exemple : `ri`

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

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

Publics cibles

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

Récupère la liste des éléments de ligne et campagnes actifs, ou de tous les éléments de ligne et campagnes, qui ciblent un custom_audience_id donné

Name	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Exemple : `18ce54d4x5t`
custom_audience_id required	Référence à l’audience personnalisée utilisée dans la requête. Type: string Exemple : `2906h`
with_active optional	Lorsque `false`, inclut les éléments de ligne dont le statut est `servable=false`. Type: boolean Valeur par défaut : `true` Valeurs possibles : `true`, `false`
cursor optional	Spécifie un curseur pour obtenir la page suivante de résultats. Voir Pagination pour plus d’informations. Type: string Exemple : `8x7v00oow`

Exemple de requête GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h/targeted Exemple de réponse

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

Utilisateurs des audiences personnalisées

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

Cet endpoint permet aux partenaires d’ajouter, de mettre à jour et de supprimer des utilisateurs d’un custom_audience_id donné. L’endpoint accepte également plusieurs types d’identifiants par utilisateur. Toutes les données fournies dans le champ users de la requête, à l’exception de partner_user_id, doivent être hachées avec SHA256 et normalisées. Requêtes par lots

La taille maximale actuelle d’un lot est de 2500 pour cet endpoint. La taille du lot est déterminée par le nombre d’opérations (Update/Delete) par requête. Par exemple, plus de 2500 objets d’opération ({"operation_type": "Update/Delete", [..] }) dans un même tableau entraînent une erreur.
La taille maximale du corps de requête POST que cet endpoint peut accepter est de 5,000,000 octets.
Les limites de taux pour cet endpoint sont de 1500 par fenêtre de 1 minute.
Tous les paramètres sont envoyés dans le corps de la requête et un Content-Type de application/json est requis.
Les requêtes par lots échouent ou réussissent ensemble en tant que groupe, et toutes les réponses de l’API, en cas d’erreur comme de succès, préservent l’ordre des éléments de la requête initiale.

Réponses par lots La réponse renvoyée par la X Ads API contient deux fields, success_count et total_count. Ces valeurs doivent toujours être égales et correspondent au nombre d’enregistrements de la requête qui ont été traités par le backend. Une situation où le nombre d’enregistrements envoyés dans le corps de la requête n’est pas égal à success_count et total_count doit être traitée comme une erreur nécessitant une nouvelle tentative. Erreurs par lots

Les erreurs au niveau de la requête (p. ex. taille maximale du lot dépassée) sont indiquées dans la réponse sous l’objet errors.
Les erreurs au niveau des éléments (p. ex. paramètres obligatoires manquants) sont indiquées dans la réponse sous l’objet operation_errors.
L’index de l’erreur dans operation_errors correspond à l’index de l’élément d’entrée, avec le message d’erreur associé.

URL de ressource

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

Paramètres

Nom	Description
operation_type requis	Le type d’opération appliqué par groupe `users` en cours d’exécution. Type : enum Valeurs possibles : `Update`, `Delete`
params requis	Un objet JSON contenant le tableau `users`, ainsi que les horodatages `effective_at` et `expires_at`. Type : JSON
users requis	Un tableau d’objets JSON contenant tous les paramètres pour un utilisateur donné. Type : JSON
effective_at optionnel	L’heure UTC à laquelle l’association à l’audience personnalisée doit prendre effet. Exprimée en ISO 8601. Par défaut : la date et l’heure actuelles. Type : string Exemple : `2017-07-05T07:00:00Z`
expires_at optionnel	L’heure UTC à laquelle l’association à l’audience personnalisée doit expirer. L’heure spécifiée doit être postérieure à la valeur de `effective_at`. Exprimée en ISO 8601. Par défaut : 13 mois à partir de l’horodatage de la requête. Type : string Exemple : `2017-07-05T07:00:00Z`

Étant donné l’approche multiclés de l’objet users, chaque élément de cet objet est documenté ci-dessous :

Nom	Description
email optionnel	Adresse(s) e‑mail de l’utilisateur. Type : Array[String]
device_id optionnel	IDFA/AdID/Android ID Type : Array[String]
handle optionnel	Le(s) @handle appartenant à l’utilisateur Type : Array[String]
twitter_id optionnel	L’ID X de l’utilisateur Type : Array[String]
phone_number optionnel	Numéro(s) de téléphone de l’utilisateur Type : Array[String]
partner_user_id optionnel	L’ID de l’utilisateur dans le système du partenaire. Type : Array[String]

Exemple de requête

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

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

Exemple de réponse

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

Autorisations des audiences personnalisées

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

Récupère les détails de certaines ou de toutes les autorisations associées à l’audience personnalisée spécifiée. URL de la ressource https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions Paramètres

Name	Description
account_id required	L’identifiant du compte exploité. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: `18ce54d4x5t`
custom_audience_id required	La référence à l’audience personnalisée utilisée dans la requête. Type: string Example: `1nmth`
count optional	Spécifie le nombre d’enregistrements à récupérer par requête distincte. Type: int Default: `200` Min, Max: `1`, `1000`
cursor optional	Spécifie un curseur pour obtenir la page suivante de résultats. Voir Pagination pour plus d’informations. Type: string Example: `8x7v00oow`
granted_account_ids optional	Restreint la réponse aux comptes souhaités en spécifiant une liste d’identifiants séparés par des virgules. Jusqu’à 200 id peuvent être fournis. Type: string Example: `18ce54aymz3`
sort_by optional	Trie selon un attribut pris en charge, par ordre croissant ou décroissant. Voir Sorting pour plus d’informations. Type: string Example: `created_at-asc`
custom_audience_permission_ids optional	Restreint la réponse aux autorisations d’audience personnalisée souhaitées en spécifiant une liste d’identifiants séparés par des virgules. Jusqu’à 200 id peuvent être fournis. Type: string Example: `ri`
with_total_count optional	Inclut l’attribut de réponse `total_count`. Remarque : Ce paramètre et `cursor` sont exclusifs. Remarque : Les requêtes incluant `total_count` auront des limites de taux plus faibles, actuellement fixées à 200 par 15 minutes. Type: boolean Default: `false` Possible values: `true`, `false`

Exemple de requête GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/permissions Exemple de réponse

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

Crée un nouvel objet d’autorisation permettant de partager l’audience spécifiée avec un compte donné. Remarque : La création ou la modification d’autorisations pour une audience personnalisée exige que l’audience appartienne au compte qui tente de modifier les autorisations. Vous pouvez vérifier la propriété d’une audience personnalisée en consultant l’attribut de réponse is_owner dans la réponse relative à une audience donnée. Remarque : Les audiences ne peuvent être partagées qu’entre des comptes publicitaires relevant de la même entreprise, ou si le compte publicitaire propriétaire de l’audience dispose de la fonctionnalité de compte SHARE_AUDIENCE_OUTSIDE_BUSINESS. Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions Parameters

Name	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : `18ce54d4x5t`
granted_account_id required	Le compte auquel vous souhaitez accorder des autorisations pour l’audience personnalisée. Type : string Exemple : `18ce54aymz3`
permission_level required	Le type d’accès à l’audience personnalisée dont doit disposer `granted_account_id`. Type : enum Valeurs possibles : `READ_ONLY`, `READ_WRITE`
custom_audience_id required	Référence de l’audience personnalisée utilisée dans la requête. Type : string Exemple : `2906h`

Example Request

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

Exemple de réponse

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

Révoque l’autorisation de partage de Custom Audience spécifiée. Remarque : La création ou la modification d’autorisations pour une Custom Audience exige que l’audience soit détenue par le compte qui tente de modifier les autorisations. Vous pouvez vérifier la propriété d’une Custom Audience en consultant l’attribut de réponse is_owner dans la réponse pour l’audience concernée. Une fois révoquée, nous garantissons que le compte destinataire de l’autorisation (granted_account_id) ne pourra pas cibler l’audience dans de futures campagnes. Les campagnes existantes continueront de s’exécuter avec les audiences partagées ; les campagnes ne s’arrêtent pas et l’audience n’est pas retirée de la campagne. Il n’est pas possible de copier cette campagne après la révocation de l’autorisation de partage de l’audience. URL de la ressource

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

Paramètres

Name	Description
account_id required	L’identifiant du compte exploité. Apparaît dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’Advertiser API, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: `18ce54d4x5t`
custom_audience_id required	Référence à la Custom Audience utilisée dans la requête. Type: string Example: `1nmth`
custom_audience_permission_id required	Référence à l’autorisation de Custom Audience utilisée dans la requête. Type: string Example: `ri`

Exemple de requête DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/permissions/ri Exemple de réponse

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

Audiences personnalisées

GET accounts/:account_id/custom_audiences

Récupère les détails de certaines ou de toutes les Audiences personnalisées associées au compte actuel. Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences Parameters

Name	Description
account_id required	L’identifiant du compte utilisé. Figure dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: `18ce54d4x5t`
count optional	Spécifie le nombre d’enregistrements à récupérer par requête. Type: int Default: `200` Min, Max: `1`, `1000`
cursor optional	Spécifie un curseur pour obtenir la page suivante de résultats. Voir Pagination pour plus d’informations. Type: string Example: `8x7v00oow`
permission_scope optional	Permet de filtrer la réponse pour n’afficher que les listes que vous possédez ou celles qui ont été partagées avec vous. Par défaut, sans préciser ce paramètre, vous ne verrez que les audiences que vous possédez. Type: enum Default: `OWNER` Possible values: `OWNER`, `SHARED`
q optional	Une query facultative pour restreindre la ressource par `name`. Note : effectue une correspondance par préfixe insensible à la casse. Type: string Min, Max length: `1`, `255`
sort_by optional	Trie selon un attribut pris en charge, par ordre croissant ou décroissant. Voir Sorting pour plus d’informations. Type: string Example: `created_at-asc`
custom_audience_ids optional	Limite la réponse aux audiences personnalisées souhaitées en spécifiant une liste d’identifiants séparés par des virgules. Jusqu’à 200 id peuvent être fournis. Type: string Example: `1nmth`
with_deleted optional	Inclure les résultats supprimés dans la requête. Type: boolean Default: `false` Possible values: `true`, `false`
with_total_count optional	Inclure l’attribut de réponse `total_count`. Note : ce paramètre et `cursor` sont exclusifs. Note : les requêtes qui incluent `total_count` auront des limites de taux plus faibles, actuellement fixées à 200 par 15 minutes. Type: boolean Default: `false` Possible values: `true`, `false`

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

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

GET accounts/:account_id/custom_audiences/:custom_audience_id

Récupérer des Custom Audiences spécifiques associées au compte en cours. Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id Parameters

Name	Description
account_id required	L’identifiant du compte exploité. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Exemple : `18ce54d4x5t`
custom_audience_id required	Référence à la Custom Audience concernée par la requête. Type: string Exemple : `2906h`
with_deleted optional	Inclure les éléments supprimés dans la réponse. Type: boolean Valeur par défaut : `false` Valeurs possibles : `true`, `false`

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

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

POST accounts/:account_id/custom_audiences

Créer une nouvelle Audience personnalisée factice associée au compte actuel. Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences Parameters

Name	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’Ads API, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: `18ce54d4x5t`
name required	Le nom d’affichage de cette audience. Une valeur de nom unique doit être utilisée. Dans le cas contraire, une erreur sera renvoyée. Type: string Example: `ads api users`
description optional	Une description de cette audience. Type: string Example: `Collection of all users of the Ads API`

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

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

PUT accounts/:account_id/custom_audiences/:custom_audience_id

Met à jour l’audience personnalisée spécifique associée au compte en cours. URL de la ressource https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id Paramètres

Nom	Description
account_id obligatoire	L’identifiant du compte exploité. Figure dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Annonceur, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : `18ce54d4x5t`
custom_audience_id obligatoire	Référence à l’audience personnalisée ciblée par la requête. Type : string Exemple : `2906h`
name optionnel	Le nom d’affichage de cette audience. Une valeur de nom unique doit être utilisée, faute de quoi une erreur sera renvoyée. Type : string Exemple : `ads api users`
description optionnel	Description de cette audience. Type : string Exemple : `Collection de tous les utilisateurs de la X Ads API`

Exemple de requête PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h?name=developers_changed Exemple de réponse

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

Permet la création par lots de Custom Audiences. Consultez la page Custom Audiences Overview pour plus d’informations sur les audiences. Remarque : Cet endpoint de lot est actuellement en bêta fermée et disponible pour une sélection d’annonceurs. Pendant cette période de bêta, seules les Flexible Audiences basées sur des audiences personnalisées mobiles peuvent être créées. Requêtes par lots

La taille maximale actuelle d’un lot est de 10.
Tous les paramètres sont envoyés dans le corps de la requête et un Content-Type de application/json est requis.
Les requêtes par lots échouent ou aboutissent ensemble en tant que groupe, et toutes les réponses de l’API, en cas d’échec comme de réussite, conservent l’ordre des éléments de la requête initiale.

Réponses par lots Les réponses de l’API par lots renvoient une collection ordonnée d’éléments. Par ailleurs, elles sont identiques, dans leur structure, à leurs endpoints correspondants pour un seul élément. Erreurs par lots

Les erreurs au niveau de la requête (p. ex. : taille maximale du lot dépassée) sont indiquées dans la réponse sous l’objet errors.
Les erreurs au niveau des éléments (p. ex. : paramètre requis manquant) sont indiquées dans la réponse sous l’objet operation_errors.

Flexible Audiences

Les Flexible Audiences sont immuables une fois créées.
Les Custom Audiences sont transmises sous forme d’arborescence avec des combinaisons de logique booléenne pour créer des Flexible Audiences.
Au maximum 10 nœuds feuilles de Custom Audiences peuvent être utilisés pour créer une Flexible Audience.

URL de la ressource https://ads-api.x.com/12/batch/accounts/:account_id/custom_audiences Paramètres

Name	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Ads, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: `18ce54d4x5t`
audience_type required	Le type d’audience à créer. Type: enum Possible values: `FLEXIBLE`, `MOBILE_AUDIENCE`
child_segments required	Un tableau d’objets qui définissent le sous-ensemble des membres d’une Custom Audience que vous souhaitez cibler. Chaque objet doit contenir un `custom_audience_id`, `frequency`, `frequency_comparator`, `lookback_window`, `negate` et, dans certains cas, des `child_segments` supplémentaires. Type: array
name required	Le nom d’affichage de l’audience. Une valeur de nom unique doit être utilisée. À défaut, une erreur se produira. Type: string Example: `my_flexible_audience_name`
operation_type required	Le type d’opération appliqué à chaque élément. Type: enum Possible values: `Create`, `Update`, `Delete`
boolean_operator sometimes required	La relation logique entre les segments enfants dans l’objet parent (contenant). Requis si `child_segments` n’est pas vide pour l’objet parent. Type: enum Possible values: `AND`, `OR`
lookback_window sometimes required	Une valeur entière indiquant l’intervalle, en jours, pendant lequel l’utilisateur a effectué l’action spécifique et a été qualifié pour la Custom Audience donnée. Type: int Possible values: `1`, `7`, `14`, `30`
segments sometimes required	Un objet contenant un `boolean_operator` et des `child_segments` qui définissent le sous-ensemble des membres d’une Custom Audience que vous souhaitez cibler. Type: object
custom_audience_id sometimes required	L’id de la Custom Audience à utiliser comme segment enfant. Type: string Example: `tyfo`
frequency optional	Une valeur entière indiquant la fréquence, dans la fenêtre de lookback, à laquelle l’utilisateur a effectué l’action spécifique et a été qualifié pour la Custom Audience donnée. Type: int Default value: `1`
frequency_comparator optional	Le comparateur du `frequency` transmis dans la requête. Note : Dans les valeurs ci-dessous, `GTE` signifie « supérieur ou égal », `LT` « inférieur à », etc. Type: string Possible values: `NUM_GTE`, `NUM_GT`, `NUM_EQ`, `NUM_LTE`, `NUM_LT` Default value: `NUM_GTE`
negate optional	Inverse le segment, qui est dès lors exclu de la combinaison. Type: boolean Default value: `true` Possible values: `true`, `false`

Exemple de requête POST https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/custom_audiences

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

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

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

                    ]
                  }
                ]
              }
            ]
          }
        }
      }
    ]

Exemple de réponse

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

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

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

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

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

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

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

DELETE accounts/:account_id/custom_audiences/:custom_audience_id

Supprime la Custom Audience spécifiée appartenant au compte en cours. URL de la ressource https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id Paramètres

Nom	Description
account_id obligatoire	L’identifiant du compte utilisé. Figure dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Exemple : `18ce54d4x5t`
custom_audience_id obligatoire	Référence à la Custom Audience ciblée par la requête. Type: string Exemple : `2906h`

Exemple de requête DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h Exemple de réponse

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

Listes à ne pas contacter

GET accounts/:account_id/do_not_reach_lists

Récupère les détails d’une ou de toutes les listes Do Not Reach associées au compte actuel. Remarque : un account_id ne peut avoir qu’une seule liste Do Not Reach au maximum. Resource URL https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists Parameters

Name	Description
account_id required	L’identifiant du compte exploité. Il apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: `18ce54d4x5t`
with_deleted optional	Inclure les résultats supprimés dans la requête. Type: boolean Default: `false` Possible values: `true`, `false`

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

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

POST accounts/:account_id/do_not_reach_lists

Créer une nouvelle Do Not Reach List associée au compte actuel. Remarque : Un account_id ne peut avoir qu’une seule Do Not Reach List au maximum. Resource URL https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists Parameters

Name	Description
account_id required	L’identifiant du compte exploité. Il apparaît dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: `18ce54d4x5t`
description optional	Une description de cette audience. Type: string Example: `A list of users to exclude`

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

    {
      "request": {
        "params": {
          "description": "Une liste d'utilisateurs à exclure",
          "account_id": "18ce54bgxky"
        }
      },
      "data": {
        "targetable": false,
        "name": "Liste de non-ciblage",
        "description": "Une liste d'utilisateurs à exclure",
        "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

Cet endpoint permet d’ajouter, de mettre à jour et de supprimer des utilisateurs d’un do_not_reach_list_id donné. Cet endpoint n’accepte que les e-mails comme type d’identifiant utilisateur valide. Toutes les données fournies dans le champ emails de la requête doivent être hachées à l’aide de SHA256 et normalisées. Notes

Un account_id ne peut avoir au maximum qu’une seule Do Not Reach List
Les utilisateurs ajoutés à cette liste doivent avoir un horodatage expires_at défini à moins de 13 mois à partir de l’horodatage actuel
L’API Do Not Reach List n’accepte pas d’horodatage effective_at et utilise par défaut l’horodatage actuel
Do Not Reach List ne supprime pas les utilisateurs d’aucune audience personnalisée du compte, mais agit comme un ciblage d’exclusion pour toutes les campagnes diffusées pour le compte

Requêtes par lot

La taille maximale actuelle d’un lot est de 2500 pour cet endpoint. La taille du lot est déterminée par le nombre d’opérations (Update/Delete) par requête. Par exemple, plus de 2500 objets d’opération ({"operation_type": "Update/Delete", [..] }) dans un seul tableau entraînent une erreur.
La taille maximale du corps de la requête POST que cet endpoint peut accepter est de 5,000,000 octets.
Les limites de taux pour cet endpoint sont de 1500 par fenêtre de 1 minute.
Tous les paramètres sont envoyés dans le corps de la requête et un Content-Type de application/json est requis.
Les requêtes par lot échouent ou réussissent ensemble en tant que groupe et toutes les réponses de l’API, tant pour les erreurs que pour les succès, préservent l’ordre des éléments de la requête initiale.

Réponses par lot La réponse renvoyée par la X Ads API contient deux champs, un success_count et un total_count. Ces valeurs doivent toujours être égales et correspondent au nombre d’enregistrements de la requête qui ont été traités par le backend. Une situation où le nombre d’enregistrements envoyés dans le corps de la requête n’est pas égal à success_count et total_count doit être traitée comme une erreur nécessitant une nouvelle tentative. Erreurs par lot

Les erreurs au niveau de la requête (p. ex. taille de lot maximale dépassée) sont indiquées dans la réponse sous l’objet errors.
Les erreurs au niveau des éléments (p. ex. paramètres obligatoires manquants) sont indiquées dans la réponse sous l’objet operation_errors.
L’index de l’erreur dans operation_errors renvoie à l’index de l’élément d’entrée, avec le message d’erreur correspondant

URL de la ressource https://ads-api.x.com/12/batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users Paramètres

Name	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: `18ce54d4x5t`
do_not_reach_list_id required	Référence à la Do Not Reach List utilisée dans la requête Type: string Example: `2906h`
operation_type required	Le type d’opération appliqué par groupe `users`. Type: enum Possible values: `Update`, `Delete`
params required	Un objet JSON contenant le tableau `emails` et l’horodatage `expires_at`. Type: JSON
users required	Un tableau d’objets JSON contenant tous les paramètres pour un utilisateur donné. Type: JSON
expires_at optional	L’heure UTC à laquelle l’association utilisateur doit expirer. L’heure spécifiée doit être postérieure à l’horodatage actuel. Exprimée en ISO 8601. Par défaut : 13 mois à compter de l’horodatage actuel. Type: string Example: `2017-07-05T07:00:00Z`

Étant donné l’approche multi-clés de l’objet users, chaque élément de cet objet est documenté ci-dessous :

Nom	Description
email facultatif	Adresse(s) e‑mail de l’utilisateur. Type : Array[String]
phone_number facultatif	Numéro(s) de téléphone de l’utilisateur Type : Array[String]

Exemple de requête

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

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

Exemple de réponse

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

DELETE accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id

Supprime la Do Not Reach List spécifiée appartenant au compte en cours. URL de ressource https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id Paramètres Aucun Exemple de requête DELETE https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists/4ofrp Exemple de réponse

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

X Ads API

Principes fondamentaux

Ressources

Mesure

​Audiences personnalisées

​Vue d’ensemble

​FAQ sur les audiences

​CRM

​Exigences de correspondance des ID partenaire

​Exigences de correspondance standard

​Nommage et opérations des fichiers de segment personnalisé

​Création et mise à jour des audiences

​Directives de hachage

​Normalisation de l’e-mail

​Normalisation des identifiants d’appareil

​Normalisation des identifiants utilisateur X

​Intégration de synchronisation d’ID

​URL du pixel

​Paramètres du pixel

​Pixel de synchronisation d’ID :

​Données utilisateur pour Custom Audiences

​Audiences personnalisées : Web

​Intégration de l’API Audience

​Présentation

​Créer une nouvelle Audience personnalisée

​Ajouter des utilisateurs à une Audience

​Supprimer des utilisateurs d’une audience

​Utilisateurs en désinscription (opt-out)

​Référence de l’API

​Informations sur les mots-clés

​GET insights/keywords/search

​Autorisations pour les audiences personnalisées

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

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

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

​Publics cibles

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

​Utilisateurs des audiences personnalisées

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

​URL de ressource

​Paramètres

​Exemple de requête

​Exemple de réponse

​Autorisations des audiences personnalisées

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

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

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

​Audiences personnalisées

​GET accounts/:account_id/custom_audiences

​GET accounts/:account_id/custom_audiences/:custom_audience_id

​POST accounts/:account_id/custom_audiences

​PUT accounts/:account_id/custom_audiences/:custom_audience_id

​POST batch/accounts/:account_id/custom_audiences

​DELETE accounts/:account_id/custom_audiences/:custom_audience_id

​Listes à ne pas contacter

​GET accounts/:account_id/do_not_reach_lists

​POST accounts/:account_id/do_not_reach_lists

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

​DELETE accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id

Audiences personnalisées

Vue d’ensemble

FAQ sur les audiences

CRM

Exigences de correspondance des ID partenaire

Exigences de correspondance standard

Nommage et opérations des fichiers de segment personnalisé

Création et mise à jour des audiences

Directives de hachage

Normalisation de l’e-mail

Normalisation des identifiants d’appareil

Normalisation des identifiants utilisateur X

Intégration de synchronisation d’ID

URL du pixel

Paramètres du pixel

Pixel de synchronisation d’ID :

Données utilisateur pour Custom Audiences

Audiences personnalisées : Web

Intégration de l’API Audience

Présentation

Créer une nouvelle Audience personnalisée

Ajouter des utilisateurs à une Audience

Supprimer des utilisateurs d’une audience

Utilisateurs en désinscription (opt-out)

Référence de l’API

Informations sur les mots-clés

GET insights/keywords/search

Autorisations pour les audiences personnalisées

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

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

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

Publics cibles

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

Utilisateurs des audiences personnalisées

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

URL de ressource

Paramètres

Exemple de requête

Exemple de réponse

Autorisations des audiences personnalisées

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

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

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

Audiences personnalisées

GET accounts/:account_id/custom_audiences

GET accounts/:account_id/custom_audiences/:custom_audience_id

POST accounts/:account_id/custom_audiences

PUT accounts/:account_id/custom_audiences/:custom_audience_id

POST batch/accounts/:account_id/custom_audiences

DELETE accounts/:account_id/custom_audiences/:custom_audience_id

Listes à ne pas contacter

GET accounts/:account_id/do_not_reach_lists

POST accounts/:account_id/do_not_reach_lists

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

DELETE accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id