> ## Documentation Index
> Fetch the complete documentation index at: https://generaltranslation.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Audiences
export const Button = ({href, children}) => {
return
;
};
## Audiences personnalisées
### Vue d’ensemble
Il existe plusieurs façons pour les partenaires de créer des [Audiences personnalisées](https://business.x.com/en/targeting/tailored-audiences.html).
* [Audience API (CRM)](#crm)
* [Web](#web)
* [Mobile](#mobile)
* [Flexible](#flexible)
Veuillez noter que vous ne pouvez pas exclure les audiences personnalisées similaires (lookalike) du ciblage. De plus, vous ne pouvez pas cibler à la fois une audience personnalisée et une audience personnalisée similaire (lookalike) au sein du même élément de campagne publicitaire (groupe de publicités).
**Gestion des audiences**
Les audiences peuvent être gérées via des partenaires d’audience et des partenaires Ads API. Nous proposons une série d’endpoints dans l’API pour accéder aux audiences personnalisées et les gérer.
Pour les informations relatives aux audiences personnalisées, nous proposons 2 endpoints :
* [GET accounts/:account\_id/custom\_audiences](/fr/x-ads-api/audiences)
* [GET accounts/:account\_id/custom\_audiences/:custom\_audience\_id](/fr/x-ads-api/audiences)
Pour plus de détails sur la façon de charger et de gérer les audiences, consultez le [guide Audience API](/fr/x-ads-api/audiences).
**Délais de traitement**
De manière générale, les modifications d’audience sont traitées par lots toutes les 6 à 8 heures. Pendant qu’une modification d’audience est en cours de traitement, l’audience existante devant être mise à 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 de temps.
**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](/fr/x-ads-api/audiences) indiquera si une audience ne peut pas être ciblée parce qu’elle correspond à un nombre insuffisant d’utilisateurs.
**Audience API (CRM)**
Les partenaires d’audience ou API fournissent une liste d’identifiants hachés et X effectue un appariement et produit des segments qui sont mis à disposition pour l’achat média sur X. Les partenaires peuvent créer ces audiences avec l’[Audience API](/fr/x-ads-api/audiences).
**Fonctionnement**
**Web**
Nous proposons un processus standard de mise en correspondance de cookies lorsque nous travaillons avec des partenaires d’audience MPP afin d’identifier les segments à cibler pour l’achat média sur X. En outre, les annonceurs peuvent configurer une balise [X Web Event Tag](/fr/x-ads-api/measurement/web-conversions#web-event-tags) pour collecter les données des utilisateurs de leur site web et créer une audience personnalisée correspondante.
**Étapes de configuration**
![]()
**Fonctionnement**
**Mobile**
Veuillez consulter [l’article de blog Custom Audiences from Mobile Apps](https://blog.x.com/2014/introducing-tailored-audiences-from-mobile-apps) pour plus de détails.
**Flexible**
Les [audiences flexibles](/fr/x-ads-api/audiences) donnent aux annonceurs la possibilité de créer et d’enregistrer des combinaisons d’audiences basées sur des audiences personnalisées existantes ou des sous-ensembles d’audiences personnalisées existantes. Les sous-ensembles des membres d’une audience personnalisée peuvent être ciblés en fonction de la récence et de la fréquence des interactions.
**Cas d’utilisation restreints pour les audiences personnalisées**
[En savoir plus sur les restrictions](https://developer.x.com/en/developer-terms/more-on-restricted-use-cases "Read more about restrictions")
### FAQ sur les audiences[](#real-time-tailored-audiences "Lien permanent vers ce titre")
**Q : Nous avons transmis une très grande quantité de données, pourquoi la taille de l’audience apparaî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 fournir la taille de l’audience ne s’exécute qu’après une certaine période. La taille correcte de l’audience devrait s’afficher dans l’interface au bout de quelques heures.
**Q : Nous avons terminé l’envoi des données d’audience et attendu 24 heures ou plus, mais nous ne pouvons toujours pas cibler l’audience – quelles doivent être 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 de membres précédentes.
* Veuillez confirmer la réponse aux 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 pouvoir faire la correspondance des utilisateurs. Les utilisateurs non mappés dans les mises à jour de membres ne seront pas traduits en utilisateurs ciblés.
Si tout le reste est confirmé comme correct et fonctionnel, veuillez contacter vos interlocuteurs produit chez X avec des informations aussi détaillées que possible (voir par exemple le [Guide to Partner Inbounds](/fr/x-ads-api/introduction) pour le type d’informations souhaité).
**Q : Combien de fois pouvons-nous appeler l’endpoint, et avec quel algorithme ?**
R : Nous vous recommandons fortement d’appeler notre système avec des deltas incrémentaux et de ne jamais renvoyer l’ensemble complet des membres de l’audience. Le système a été testé avec un débit suffisant pour traiter des mises à jour de données incrémentales pour certains des plus grands sites Web au monde. Le chargement initial des audiences doit être soigneusement limité, et il est prévu que ce premier chargement prenne un temps significatif pour se terminer.
**Q : Quelle est la taille minimale d’une audience pouvant être utilisée pour le ciblage ?**
* La taille minimale d’une audience est de 100 utilisateurs (après correspondance). Si une audience avec moins de 500 utilisateurs est mise en correspondance, elle ne sera pas disponible pour le ciblage dans l’interface utilisateur X Ads.
**Q : Combien de temps faudra-t-il pour traiter les fichiers d’audience ? Et combien de temps faudra-t-il pour que les fichiers d’audience soient prêts dans l’interface utilisateur X ?**
* Le traitement des fichiers d’audience prend généralement 4 à 6 heures, mais cela dépendra de la taille du fichier. Une fois le fichier traité, les audiences sont disponibles dans l’interface utilisateur 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 d’annonceur. Nous pourrons alors vérifier que le fichier est correctement ingéré et chargé dans l’interface X.
**Q : Qu’est-ce qu’un identifiant utilisateur partenaire (`p_user_id`) ?**
* C’est l’identifiant utilisé par votre entreprise pour identifier de manière unique chacun de vos clients.
**Q : Qu’est-ce qu’un ID standard ?**
* Cela peut être une adresse e-mail, un device ID, un @handle X ou un ID.
**Q : Comment puis-je obtenir la clé HMAC ?**
* Elle sera fournie par un e-mail chiffré. Veuillez fournir votre clé PGP publique à [mpp-inquiry@x.com](mailto:mpp-inquiry%x.com) et nous vous enverrons un e-mail de test pour vérifier que tout fonctionne. Une fois la vérification effectuée, nous vous enverrons la clé HMAC.
**Q : Comment puis-je vérifier que le processus de hachage a fonctionné en utilisant la clé HMAC fournie ?**
* X fournira un fichier de test (contenant des exemples d’adresses e-mail, de device IDs, etc.) et un fichier de hachage résultant, que vous pourrez utiliser pour vérifier vos résultats.
**Q : Y a-t-il une limite de taille pour le fichier de correspondance de données complet ?**
* Non, il n’y a pas de limite de taille pour le fichier de correspondance de données complet.
**Q : Combien de temps faudra-t-il pour traiter le fichier de correspondance de données complet ?**
* Une fois le fichier reçu par X, il faudra environ 1 jour pour traiter le fichier.
### CRM
Ce document décrit les modalités d’intégration pour les partenaires Custom Audiences CRM, y compris les formats de fichiers et le processus d’échange de données.
**Résumé**
La société fournira à X, au nom d’un client, une liste d’identifiants utilisateur courants hachés (c.-à-d. des adresses e‑mail) ou des id utilisateur du partenaire, afin d’effectuer une correspondance à l’aveugle et de produire une liste d’id d’utilisateur X pour le ciblage. Les segments de ciblage seront mis à la disposition du compte annonceur, via le @handle spécifique indiqué par le nom de fichier dans la configuration de campagne sur ads.x.com.
Tous les fichiers provenant de la société seront fournis à X au moyen d’un package sécurisé sur IronBox ([www.golockbox.com](http://www.golockbox.com)), à l’aide d’un compte spécifique accordé à la société par X. X fournira l’accès à IronBox. La documentation sur les API IronBox est disponible à l’adresse [https://secure.goironcloud.com/Docs/Help/](https://secure.goironcloud.com/Docs/Help/).
#### Exigences de correspondance des ID de partenaire
Si l’entreprise utilise son propre système standard d’ID pour suivre les utilisateurs (c.-à-d. pas d’identifiants utilisateur courants comme les adresses e‑mail, les id d’appareil, l’ID utilisateur X, etc.), alors il s’agit du processus recommandé.
**1. Correspondance de données complète**
Initialement, l’entreprise fournira, dans un fichier unique, une liste exhaustive de tous les enregistrements utilisateur qui incluent avec X un identifiant utilisateur courant unique, afin d’effectuer une correspondance de données complète et de produire une table de correspondance, stockée par X, entre les ID partenaire (`p_user_id`) et les ID X (`tw_id`). Cette opération sera effectuée régulièrement tous les 2 à 3 mois pour garantir une mise à jour correcte. Une fois la correspondance terminée, X communiquera à l’entreprise, par e‑mail, 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 Instructions de hachage ci‑dessous pour les identifiants utilisateur courants
**2. Listes de segments personnalisés**
L’entreprise fournira des listes d’utilisateurs sous forme de `p_user_id` pour créer des audiences personnalisées pour les clients, en vue d’un ciblage sur X.
* Valeurs séparées par des sauts de ligne
* `p_user_id`
* * (Identique à ce qui est fourni dans la section 1. Correspondance de données complète ci‑dessus. Si la valeur fournie dans la correspondance de données 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 non hachée.)
#### Exigences de correspondance standard
Si l’entreprise n’utilise pas un identifiant standard pour la mise en correspondance de tous les identifiants utilisateur clients, le processus recommandé est le suivant.
**Listes de segments personnalisés**
L’entreprise fournira directement à X, au nom de ses 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 retours à la ligne
* Identifiant utilisateur courant haché (c.-à-d. adresse e-mail)
* Suivre les conventions de nommage de fichiers décrites ci-dessous
* Suivre les instructions de hachage pour les adresses e-mail ci-dessous (voir la section Instructions de hachage)
#### Nommage et opérations des fichiers de liste de segments personnalisés
Le traitement appliqué à un fichier est déterminé par le nom du fichier, avec les opérations suivantes disponibles et la convention générale de nommage suivante : audiencename\_partnername.handle.operation.filetype
* audiencename : le nom de l’audience personnalisée. Ce champ est le nom qui sera affiché lors de la sélection de l’audience dans l’interface de configuration des campagnes ads.x.com, par exemple brand\_loyalty\_card\_holders.
* partnername : nom de la société fournissant les données pour le compte de l’annonceur, par exemple company\_name.
* handle : compte X (@handle) qui aura accès aux audiences personnalisées, par exemple @pepsi, @dietpepsi.
* operation : new, add, remove, removeall, replace (détails ci‑dessous)
* timestamp : horodatage Unix (epoch) standard en secondes, utilisé pour garantir que chaque fichier d’audience téléversé est unique
* filetype : le fichier doit être au format \*.txt
#### Création et mise à jour des audiences
Créer une nouvelle audience avec un seul fichier, par exemple loyalty\_card\_holders\_partnername.pepsi.new\.txt
Add - 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 dans une audience existante, par exemple loyalty\_card\_holders\_partnername.pepsi.remove..txt
Remove All - Supprimer les correspondances produites à partir d’une liste cumulative régulièrement mise à jour de toutes les audiences pour ce client (c’est‑à‑dire la liste de désinscription du Client). Ex : partnername.pepsi.removeall.txt
* Ceci peut être utilisé pour une liste exhaustive d’utilisateurs qui se sont 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 utilisateurs X correspondants 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
Overall Company Opt-Out - 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 exemple loyalty\_card\_holders\_partnername.pepsi.delete.txt
#### Instructions de hachage
X partagera de façon sécurisée, via PGP, une clé de production encodée en Base64 pour le hachage des identifiants utilisateur courants (c.-à-d. des adresses e-mail). L’entreprise effectuera le décodage Base64 de la clé afin de produire une clé de 32 octets qui sera utilisée 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 simple aux identifiants utilisateur courants avant le hachage (sauf pour les Device IDs, voir la section « Normalisation des ID d’appareil »).
#### Normalisation des e-mails
En d’autres termes, supprimez les espaces au début et à la fin, puis mettez également 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 hachée : 74d9584eded0ad1e5572a1c1849f3716751d371d6117a6155dad5363f4b4fbec
Remarque : le nombre exact de caractères, aussi bien pour le HMAC encodé que pour la clé, peut varier en fonction de l’entrée et de l’encodage ; le nombre de caractères précis peut donc différer.
#### Normalisation des identifiants d’appareil
Nous appliquerons les mêmes exigences en matière de hachage des identifiants d’appareil à l’aide de l’algorithme de hachage SHA-256 et d’un sel commun que nous mettons à disposition de nos partenaires de données. Nous supprimons les espaces comme nous le faisons pour les adresses e-mail, mais il n’y a aucune normalisation en minuscules pour les IDFA/identifiants Android et le format exact de l’IDFA/de l’identifiant Android doit être utilisé.
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 ID utilisateur X
Les ID X continueront d’être hachés, car le regroupement des données – par exemple une Liste de clients composée de @handles – reste privé pour l’annonceur, même s’il ne s’agit pas de données personnelles (PII). Nous appliquerons les mêmes exigences de hachage des ID X à l’aide de l’algorithme de hachage SHA-256 et d’un sel (« salt ») commun que nous fournissons aux partenaires de données. Les espaces doivent être supprimés à la fois de l’ID X et du `@`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 username.
Le format brut de l’ID sera :
* User ID : 27674040
* @username : testusername
User ID haché : bf6b57d4e861e83bea8bbed2b800b251a64c95468ee6e8cb07c3368c9ed45e85
@username haché : 12201ae78ad1afa907c7112d17f498154ffb0bf9ea523f5390e072a06d7d9812
### Intégration de synchronisation d’ID
Les partenaires qui envoient des données avec un `p_id` doivent passer par un processus de synchronisation d’ID afin de générer une correspondance entre les identifiants utilisateur de l’annonceur ou du partenaire et les identifiants utilisateur X. Cela permet aux annonceurs de cibler directement leurs propres segments d’utilisateurs sur X. Les partenaires doivent également attribuer au paramètre `user_identifier_type` la valeur `TALIST_PARTNER_USER_ID` ou `TAWEB_PARTNER_USER_ID` lorsqu’ils envoient leurs mises à jour d’appartenance.
* **Web uniquement** : cela peut se faire en plaçant un pixel sur le site de l’annonceur, comme indiqué ci‑dessous.
* **Liste** : cela peut se faire en utilisant l’une des méthodes décrites sur la page [CRM](/fr/x-ads-api/audiences#crm).
| | |
| :------------ | :-------------------------------------------------------- |
| **Paramètre** | **Description** |
| `p_id` | Votre identifiant de partenaire attribué par X |
| `p_user_id` | L’identifiant de l’utilisateur dans le système partenaire |
#### Pixel de synchronisation d'ID :
En utilisant un exemple d'id partenaire égal à 111 et un exemple de `p_user_id` égal à abc, le pixel généré serait le suivant :
```json theme={null}
```
**Configuration des fichiers de désinscription et envoi des fichiers de désinscription**
Les partenaires doivent fournir à X une liste d’utilisateurs qui, à leur connaissance, ont choisi de se désinscrire de la diffusion de publicités ciblées. Le fichier doit être au format suivant :
| | | | |
| :---------------- | :---------------------------------- | :-------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Column Number** | **Column Name** | **Column Type** | **Description** |
| 1 | Partner ID | string | Le « partner id » est l’ID qu’X fournit au partenaire afin d’identifier de manière unique chaque partenaire. |
| 2 | The user’s id in the partner system | string | Le `p_user_id` est l’ID unique utilisé par le partenaire pour identifier l’utilisateur. Le fichier contenant ces utilisateurs désinscrits doit être téléversé à l’aide de l’endpoint [TON upload](/fr/x-ads-api/audiences) et le chemin des données téléversées doit être envoyé à l’endpoint Global Opt Out ici : [PUT accounts/:account\_id/custom\_audiences/global\_opt\_out](/fr/x-ads-api/audiences). |
**Envoi des mises à jour d’appartenance**
Comme indiqué dans la documentation de notre endpoint, lorsque vous transmettez des utilisateurs via l’endpoint [POST custom\_audience\_memberships](/fr/x-ads-api/audiences), vous devez transmettre un customer ID (ID client) pour activer la correspondance basée sur les cookies. Les partenaires qui envoient des données 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 répertoriées dans le [Guide d’intégration de l’API Real-Time Audience](/fr/x-ads-api/audiences).
### Données utilisateur des Custom Audiences
Ce document décrit le format des données utilisateur des \[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 mis en majuscules, avec des tirets ; ex. : `2f5f5391-3e45-4d02-b645-4575a08f86e`
* Android id - le format d’origine sur l’appareil est requis, non mis en majuscules, sans tirets ni espaces ; ex. : `af3802a465767e36`
**Adresses e‑mail** :
* en minuscules, supprimer les espaces de début et de fin ; ex. : `support@x.com`
**Noms d’utilisateur X** :
* sans @, en minuscules, et suppression des espaces de début et de fin ; ex. : `jack`
**ID 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 hachage final produit doit être en minuscules. Par exemple : 49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d et **non** 49E0BE2AECCFB51A8DEE4C945C8A70A9AC500CF6F5CB08112575F74DB9B1470D
```
# hachage de l'utilisateur @AdsAPI avec Python
import hashlib
hashlib.sha256("adsapi".encode()).hexdigest()
#output
49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d
```
Des exemples de code supplémentaires pour le hachage sont disponibles sur [github.com/xdevplatform/ads-platform-tools](https://github.com/xdevplatform/ads-platform-tools).
### Audiences personnalisées : Web
**Information**
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 (ID Sync) 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 utilisateur X pouvant être utilisées pour le ciblage. Ces audiences personnalisées seront mises à disposition sur le @handle spécifique de l’annonceur, indiqué par le libellé lors de la configuration de campagne Custom Audiences Web sur ads.x.com.
X fournira le pixel sécurisé qui pourra être intégré dans les balises et sur les sites des partenaires afin de faire correspondre les ID (`p_user_ids`) aux ID utilisateur 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](https://analytics.x.com/i/adsct?p\_user\_id=xyz\&p\_id=123)
**`p_user_id`** - xyz représente l’ID utilisateur du 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) pouvant être utilisés pour ingérer régulièrement le fichier de ciblage. Un exemple d’endpoint HTTPS se présentera comme suit :
```
https:///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 comprendront les fichiers suivants :
1. Partner Targeting User File
2. Targeting Conversion File
Tous les fichiers seront au format TSV, où les différents champs de chaque ligne sont séparés les uns des autres par un caractère de tabulation. Les valeurs de champs valides ne contiendront jamais le caractère de tabulation.
**Plage d’adresses IP X autorisées :**
Voici la plage d’adresses IP pouvant être autorisées pour accéder au Partner Endpoint.
* 199.16.156.0/22
* 199.59.148.0/22
**Partner Targeting User File :**
| **Column Number** | **Column Name** | **Column Type** | **Description** |
| :---------------- | :--------------- | :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 | partner id | string | Le « partner id » est l’identifiant qu’X fournit au partenaire afin d’identifier chaque partenaire de façon unique. |
| 2 | advertiser id | string | L’« advertiser id » est le @handle de l’annonceur. |
| 3 | p\_user\_id | string | Le « p\_user\_id » est l’identifiant unique utilisé par le partenaire pour identifier l’utilisateur. |
| 3 | confidence score | integer | Le « confidence score » est facultatif. Nous recommandons d’utiliser une valeur de confidence score comprise entre 0 et 100. Si le cas d’usage est le reciblage, alors un confidence score de « 100 » correspond à un utilisateur qui a été directement reciblé. Toute valeur de 0 à 99 correspondrait au niveau de confiance pour le profil similaire (look-alike). |
| 4 | segment label | string | Le « segment label » est facultatif. Les partenaires peuvent utiliser le « segment label » pour spécifier, par exemple, des catégories de produits. Nous recommandons d’utiliser ce « segment label », car il s’agit du nom lisible pour les Custom Audiences dans l’interface ads.x.com. |
**Remarques :**
Chaque fois que nous recevons un nouveau Partner Targeting File, 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’une liste incrémentale, sauf accord contraire. Nous conviendrons avec chaque partenaire de la fréquence de livraison de ce Partner Targeting File. Si nous ne recevons pas de Partner Targeting File 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
### Vue d’ensemble
L’Audience API a été lancée dans le cadre de la [v4](/fr/x-ads-api/introduction) de l’Ads API et apporte plusieurs améliororations par rapport aux anciens endpoints Audiences. Ce nouveau endpoint s’appuie sur un nouveau backend de traitement des Audiences et fournit 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 téléversement et de gestion d’Audience.
La documentation de référence est disponible sur la page de référence de l’[Audience API](/fr/x-ads-api/audiences).
**Remarque** : toutes les données utilisateur d’Audience doivent être hachées en SHA-256 avant le téléversement. Davantage 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](/fr/x-ads-api/audiences).
**Modifications de la fonctionnalité Audience**
Les changements suivants apportés aux Audiences personnalisées ont été introduits à partir de la v4 et tous les endpoints obsolètes ne seront plus disponibles une fois que la v3 de l’Ads API aura été 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
* Audience personnalisée :
* Le paramètre `list_type` sera supprimé de la requête et de la réponse sur tous les endpoints [Custom Audience](/fr/x-ads-api/audiences). Ce paramètre était auparavant utilisé pour identifier le type d’identifiant utilisateur de l’Audience (c.-à-d. email, X User ID, etc.). Cependant, les Audiences peuvent désormais accepter plusieurs identifiants utilisateur pour une même Audience, ce qui rend cette valeur non pertinente.
* Général :
* La période de rétrospection (lookback window) de l’Audience a été mise à jour pour faire correspondre les utilisateurs actifs au cours des 90 derniers jours (au lieu de 30 jours).
* Le nombre minimum d’utilisateurs correspondants requis pour qu’une Audience soit ciblable a été réduit à 100 utilisateurs (au lieu de 500 utilisateurs).
**Prérequis**
* Accès à l’Ads API
* Pour accéder au endpoint Audience, vous devrez être ajouté à une allowlist. Veuillez remplir ce formulaire et accepter le nouvel [X Ads Products and Services Agreement](/fr/x-ads-api/introduction) si vous aviez initialement accepté une version antérieure au 1er août 2018.
**Processus de téléversement d’Audience**
Le tableau suivant répertorie les principales différences entre les anciens et les nouveaux flux de création d’Audience, avec plus de détails disponibles plus bas :
| Étape du processus | Audience API | (Obsolète) téléversement TON |
| :--------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------- |
| Créer une Audience « coquille » | 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 le [Audience endpoint](/fr/x-ads-api/audiences) | Utiliser `operation` `ADD` avec le endpoint [POST custom\_audience\_changes](/fr/x-ads-api/audiences) |
| Supprimer un utilisateur | Utiliser `operation_type` `Delete` avec le [Audience endpoint](/fr/x-ads-api/audiences) | Utiliser `operation` `REMOVE` avec le endpoint [POST custom\_audience\_changes](/fr/x-ads-api/audiences) |
| Exclure des utilisateurs (opt-out) | Utiliser `operation_type` `Delete` avec le [Audience endpoint](/fr/x-ads-api/audiences) et les `custom_audience_id` correspondants dont l’utilisateur fait partie | Utiliser le [Global opt-out endpoint](/fr/x-ads-api/audiences) |
**Remarque** : toutes les Audiences mises à jour ou pour lesquelles un opt-out est effectué via le flux de téléversement TON doivent disposer d’une liste correspondante téléversée via le endpoint [TON Upload](/fr/x-ads-api/audiences) et associée à une Audience à l’aide du endpoint [custom\_audience\_changes](/fr/x-ads-api/audiences).
**Limitation de débit**
Le endpoint Audience API a une limite de débit 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 (payload). Les seules contraintes sur la charge utile sont :
1. Nombre total d’opérations : 2500 opérations
2. 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 une nouvelle Audience personnalisée « vide » à l’aide de l’endpoint \[POST custom\_audience]/x-ads-api/audiences et récupérez l’`id` de l’Audience personnalisée correspondante. 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 l’endpoint [POST accounts/:account\_id/custom\_audiences/:custom\_audience\_id/users](/fr/x-ads-api/audiences) 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](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 à titre 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 la valeur `Update` pour le champ `operation_type`. La nouvelle interface Audience permet d’envoyer plusieurs clés d’utilisateur pour un même utilisateur. Chaque objet dans le tableau d’objets JSON correspond à un seul utilisateur. En utilisant 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
De manière similaire au processus décrit pour l’ajout d’utilisateurs, des utilisateurs peuvent être supprimés d’une audience de la manière suivante :
POST [https://ads-api.x.com/11/accounts/18ce54d4x5t/custom\_audiences/1nmth/users](https://ads-api.x.com/11/accounts/18ce54d4x5t/custom\_audiences/1nmth/users)
```
# Toutes les valeurs doivent être hachées ; les valeurs non hachées sont utilisées dans cet exemple à titre 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 la valeur `Delete` et les utilisateurs seront mis en correspondance sur n’importe laquelle des clés qui étaient présentes lors de leur ajout à l’audience. Par exemple, si un utilisateur a été ajouté à une audience à l’aide d’un `email` et d’un `twitter_id`, alors ce même utilisateur peut être supprimé en utilisant l’une quelconque de ces clés, c’est‑à‑dire `email` ou `twitter_id`, ou les deux.
Il est également possible d’ajouter et de supprimer des utilisateurs d’une audience dans la même requête. Le point de terminaison prend en charge plusieurs valeurs de `operation_type` par requête.
#### Utilisateurs ayant refusé l’utilisation
Avec l’abandon de l’endpoint global d’opt-out, les partenaires doivent `Delete` tous les utilisateurs qui ont choisi l’opt-out d’une Audience. Il existe plusieurs façons d’y parvenir :
1. Suivre quels utilisateurs font partie de quelles Audiences et retirer ces utilisateurs individuellement de chaque Audience.
2. Retirer l’utilisateur de **toutes** les Audiences associées à un compte Ads.
**Bonnes pratiques générales**
* Nous recommandons fortement d’appeler cet endpoint avec des lots traités en quasi temps réel afin d’éviter des pics dans les files d’attente, qui prennent plus de temps à être traités et génèrent en général une charge inutile sur notre système. Cela garantit également que les utilisateurs sont disponibles plus rapidement pour le ciblage des campagnes.
* Un appel d’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 par nature, c’est-à-dire que soit l’intégralité de la requête réussit, soit, en cas de `errors`, 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 l’erreur et de réessayer la requête avec l’intégralité du payload.
* En cas d’échec, il est recommandé aux partenaires d’utiliser une approche de [backoff exponentiel](https://en.wikipedia.org/wiki/Exponential_backoff) avec des tentatives de nouvelle exécution. Par exemple, réessayez immédiatement après le premier échec, réessayez après 1 minute après le deuxième échec et réessayez après 5 minutes après le troisième échec consécutif, et ainsi de suite.
## Référence de l’API
### Analyses de mots-clés
#### GET insights/keywords/search[](#get-insights-keywords-search "Permalink to this headline")
À partir d’un groupe de mots-clés, récupère le volume de Tweets associé ainsi qu’un ensemble de 30 mots-clés connexes. Le volume de Tweets correspond uniquement aux mots-clés en entrée, et non aux mots-clés connexes.
Une plage de temps maximale (`end_time` - `start_time`) de 7 jours est autorisée.
Veuillez noter que les résultats sont limités à une seule zone géographique (pays).
**Resource URL[](#resource-url "Permalink to this headline")**
`https://ads-api.x.com/12/insights/keywords/search`
**Parameters[](#parameters "Permalink to this headline")**
| Name | Description |
| :----------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| granularity *required* | Spécifie la granularité des données renvoyées pour la plage de temps définie par `start_time` et `end_time`. Par exemple, lorsqu’elle est définie sur `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* | Chaîne de mots-clés séparés par des virgules pour affiner la recherche. Tous les mots-clés sont reliés entre eux par l’opérateur logique OR.
**Remarque** : un maximum de 10 mots-clés (`keywords` et `negative_keywords` combinés) peut être utilisé.
Type : string
Exemple : `developers` |
| start\_time *required* | Restreint les données récupérées à celles collectées dans la fenêtre de temps comprise entre `start_time` et `end_time`. Exprimé au format [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
Type : string
Exemple : `2017-07-10T00:00:00Z` |
| end\_time *optional* | Restreint les données récupérées à celles collectées dans la fenêtre de temps comprise entre `start_time` et `end_time`. Exprimé au format [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
**Remarque** : la valeur par défaut est l’heure actuelle.
Type : string
Exemple : `2017-07-11T00:00:00Z` |
| location *optional* | Valeur de ciblage obtenue à partir du point de terminaison [GET targeting\_criteria/locations](/fr/x-ads-api/campaign-management#get-targeting-criteria-locations) pour restreindre les résultats en fonction de l’emplacement de l’utilisateur du compte. Notez qu’à l’heure actuelle, seuls les emplacements au niveau du pays sont pris en charge.
Type : string
Exemple : `0ce8b9a7b2742f7e` |
| negative\_keywords *optional* | Chaîne de mots-clés séparés par des virgules à exclure. Tous les mots-clés négatifs sont reliés entre eux par l’opérateur logique OR.
**Remarque** : un maximum de 10 mots-clés (`keywords` et `negative_keywords` combinés) peut être utilisé.
#### GET accounts/:account\_id/tailored\_audiences/:tailored\_audience\_id/permissions[](#get-accounts-account-id-tailored-audiences-tailored-audience-id-permissions "Permalink vers ce titre")
Récupère les détails de certaines ou de l’ensemble des autorisations associées à l’audience personnalisée spécifiée.
**URL de la ressource[](#resource-url "Permalink vers ce titre")**
`https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions`
**Paramètres[](#parameters "Permalink vers ce titre")**
| Nom | Description |
| :----------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *requis* | 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](/fr/x-ads-api/campaign-management#accounts). Le compte spécifié doit être associé à l’utilisateur authentifié.
Type : string
Exemple : `18ce54d4x5t` |
| tailored\_audience\_id *requis* | Une référence à l’audience personnalisée avec laquelle vous interagissez dans la requête.
Type : string
Exemple : `1nmth` |
| count *optionnel* | Indique le nombre d’enregistrements à récupérer par requête distincte.
Type : int
Valeur par défaut : `200` Min, Max : `1`, `1000` |
| cursor *optionnel* | Indique un curseur pour obtenir la page de résultats suivante. Voir [Pagination](/fr/x-ads-api/introduction) pour plus d’informations.
Type : string
Exemple : `8x7v00oow` |
| granted\_account\_ids *optionnel* | Limite la réponse aux comptes souhaités en indiquant une liste d’identifiants séparés par des virgules. Jusqu’à 200 identifiants peuvent être fournis.
Type : string
Exemple : `18ce54aymz3` |
| sort\_by *optionnel* | Trie selon un attribut pris en charge, par ordre croissant ou décroissant. Voir [Sorting](/fr/x-ads-api/introduction) pour plus d’informations.
Type : string
Exemple : `created_at-asc` |
| tailored\_audience\_permission\_ids *optionnel* | Limite la réponse aux autorisations d’audience personnalisée souhaitées en indiquant une liste d’identifiants séparés par des virgules. Jusqu’à 200 identifiants peuvent être fournis.
Type : string
Exemple : `ri` |
| with\_total\_count *optionnel* | Inclut l’attribut de réponse `total_count`.
**Remarque** : Ce paramètre et `cursor` sont mutuellement exclusifs.
**Remarque** : Les requêtes qui incluent `total_count` seront soumises à des limites de taux plus faibles, actuellement définies à 200 par 15 minutes.
Type : boolean
Valeur par défaut : `false` Valeurs possibles : `true`, `false` |
**Exemple de requête[](#example-request "Permalink vers ce titre")**
`GET https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/1nmth/permissions`
**Exemple de réponse[](#example-response "Permalink vers ce titre")**
```
{
"request": {
"params": {
"account_id": "18ce54d4x5t",
"tailored_audience_id": "1nmth"
}
},
"next_cursor": null,
"data": [
{
"tailored_audience_id": "1nmth",
"permission_level": "READ_ONLY",
"id": "ri",
"created_at": "2017-06-08T23:17:59Z",
"granted_account_id": "18ce54aymz3",
"updated_at": "2017-06-08T23:17:59Z",
"deleted": false
}
]
}
```
#### POST accounts/:account\_id/tailored\_audiences/:tailored\_audience\_id/permissions[](#post-accounts-account-id-tailored-audiences-tailored-audience-id-permissions "Permalien vers ce titre")
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 des 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 renvoyée pour une audience donnée.
**Remarque** : les audiences ne peuvent être partagées qu’entre des comptes publicitaires appartenant à la même entreprise ou si le compte publicitaire qui possède l’audience dispose de la fonctionnalité de compte `SHARE_AUDIENCE_OUTSIDE_BUSINESS`.
**URL de la ressource[](#resource-url "Permalien vers ce titre")**
`https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions`
**Paramètres[](#parameters "Permalien vers ce titre")**
| Nom | 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](/fr/x-ads-api/campaign-management#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 sur 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* | Une référence à l’audience personnalisée que vous utilisez dans la requête.
Type : string
Exemple : `2906h` |
**Exemple de requête[](#example-request "Permalien vers ce titre")**
`POST https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/2906h/permissions?granted_account_id=18ce54aymz3&permission_level=READ_ONLY`
**Exemple de réponse[](#example-response "Permalien vers ce titre")**
```
{
"request": {
"params": {
"account_id": "18ce54d4x5t",
"granted_account_id": "18ce54aymz3",
"permission_level": "READ_ONLY",
"tailored_audience_id": "2906h"
}
},
"data": {
"tailored_audience_id": "2906h",
"permission_level": "READ_ONLY",
"id": "14m",
"created_at": "2017-09-12T23:49:34Z",
"granted_account_id": "18ce54aymz3",
"updated_at": "2017-09-12T23:49:34Z",
"deleted": false
}
}
```
#### DELETE accounts/:account\_id/tailored\_audiences/:tailored\_audience\_id/permissions/:tailored\_audience\_permission\_id[](#delete-accounts-account-id-tailored-audiences-tailored-audience-id-permissions-tailored-audience-permission-id "Permalink to this headline")
Révoquez l’autorisation de partage de la Tailored Audience spécifiée.
**Remarque** : la création ou la modification d’autorisations pour une Tailored Audience nécessite que l’audience appartienne au compte qui tente de modifier les autorisations. Vous pouvez vérifier la propriété d’une Tailored Audience en consultant l’attribut de réponse `is_owner` dans la réponse pour une audience donnée.
Une fois révoquée, nous garantissons que le compte bénéficiaire (`granted_account_id`) ne pourra plus 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 supprimée de la campagne. Il n’est pas possible de dupliquer cette campagne après la révocation de l’autorisation de partage d’audience.
**URL de la ressource[](#resource-url "Permalink to this headline")**
`https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions/:tailored_audience_permission_id`
**Paramètres[](#parameters "Permalink to this headline")**
| Nom | 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](/fr/x-ads-api/campaign-management#accounts). Le compte spécifié doit être associé à l’utilisateur authentifié.
Type: string
Example: `18ce54d4x5t` |
| tailored\_audience\_id *required* | Une référence à la Tailored Audience utilisée dans la requête.
Type: string
Example: `1nmth` |
| tailored\_audience\_permission\_id *required* | Une référence à l’autorisation de Tailored Audience utilisée dans la requête.
Type: string
Example: `ri` |
**Exemple de requête[](#example-request "Permalink to this headline")**
`DELETE https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/1nmth/permissions/ri`
**Exemple de réponse[](#example-response "Permalink to this headline")**
```
{
"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
}
}
```
### Audiences ciblées
#### GET accounts/:account\_id/custom\_audiences/:custom\_audience\_id/targeted[](#get-accounts-account-id-custom-audiences-custom-audience-id-targeted "Permalien vers ce titre")
Récupérer une liste des line items et campagnes actifs, ou de l’ensemble des line items et campagnes qui ciblent un `custom_audience_id` donné.
| Nom | 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](/fr/x-ads-api/campaign-management#accounts). Le compte spécifié doit être associé à l’utilisateur authentifié.
Type: string
Exemple : `18ce54d4x5t` |
| custom\_audience\_id *required* | Une référence à la custom audience que vous utilisez dans la requête.
Type: string
Exemple : `2906h` |
| with\_active *optional* | Lorsque `false`, inclut les line items 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. Consultez la section [Pagination](/fr/x-ads-api/introduction) pour plus d’informations.
#### POST accounts/:account\_id/custom\_audiences/:custom\_audience\_id/users[](#post-accounts-account-id-custom-audiences-custom-audience-id-users "Permalien vers ce titre")
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 utilisateur pour un même utilisateur.
Toutes les données fournies dans le champ `users` de la requête, **sauf** `partner_user_id`, doivent être hachées à l’aide de `SHA256` et [normalisées](/fr/x-ads-api/audiences#twitter-user-id-normalization).
**Requêtes en 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 même tableau entraînent une erreur.
* La taille maximale du corps POST de la requête 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 en lot échouent ou réussissent toutes ensemble en tant que groupe et toutes les réponses de l’API, qu’il s’agisse d’erreurs ou de succès, préservent l’ordre des éléments de la requête initiale.
**Réponses en lot**
La réponse renvoyée par l’API Ads contient deux champs, un `success_count` et un `total_count`. Ces valeurs doivent toujours être égales, et elles correspondent au nombre d’enregistrements dans 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 en lot**
* Les erreurs au niveau de la requête (par 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 (par 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 correspondant.
#### URL de ressource[](#resource-url "Permalien vers ce titre")
#### Paramètres[](#parameters "Permalink to this headline")
| Name | Description |
| :-------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| operation\_type *required* | Le type d’opération effectué pour chaque groupe de `users`.
Type : enum
Valeurs possibles : `Update`, `Delete` |
| params *required* | Un objet JSON contenant le tableau `users`, ainsi que les horodatages `effective_at` et `expires_at`.
Type : JSON |
| users *required* | Un tableau d’objets JSON contenant tous les paramètres pour un utilisateur donné.
Type : JSON |
| effective\_at *optional* | L’heure UTC à laquelle l’association ou les associations à l’audience personnalisée doivent prendre effet. Exprimée au format [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). Par défaut, la date et l’heure actuelles.
Type : string
Exemple : `2017-07-05T07:00:00Z` |
| expires\_at *optional* | L’heure UTC à laquelle l’association ou les associations à l’audience personnalisée doivent expirer. L’heure spécifiée doit être postérieure à la valeur de `effective_at`. Exprimée au format [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). Par défaut, 13 mois après l’horodatage de la requête.
Type : string
Exemple : `2017-07-05T07:00:00Z` |
Compte tenu de l’approche multi-clés pour l’objet `users`, chaque élément de cet objet est documenté ci‑dessous :
| Name | Description |
| :---------------------------------- | :------------------------------------------------------------------------------------ |
| email *optional* | Adresse(s) e‑mail de l’utilisateur.
Type : Array\[String] |
| device\_id *optional* | IDFA/AdID/Android ID
Type : Array\[String] |
| handle *optional* | Le ou les @handles appartenant à l’utilisateur
Type : Array\[String] |
| twitter\_id *optional* | L’ID X appartenant à l’utilisateur
Type : Array\[String] |
| phone\_number *optional* | Numéro(s) de téléphone de l’utilisateur
Type : Array\[String] |
| partner\_user\_id *optional* | L’ID de l’utilisateur dans le système du partenaire.
Type : Array\[String] |
#### Exemple de requête[](#example-request "Permalink to this headline")
#### GET accounts/:account\_id/custom\_audiences/:custom\_audience\_id/permissions[](#get-accounts-account-id-custom-audiences-custom-audience-id-permissions "Permalien vers ce titre")
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[](#resource-url "Permalien vers ce titre")**
`https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions`
**Paramètres[](#parameters "Permalien vers ce titre")**
| Nom | 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](/fr/x-ads-api/campaign-management#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 que vous utilisez dans la requête.
Type : string
Exemple : `1nmth` |
| count *optional* | Spécifie le nombre d’enregistrements à tenter de récupérer par requête distincte.
Type : int
Valeur par défaut : `200` Min, max : `1`, `1000` |
| cursor *optional* | Spécifie un curseur pour obtenir la page de résultats suivante. Voir [Pagination](/fr/x-ads-api/introduction) pour plus d’informations.
Type : string
Exemple : `8x7v00oow` |
| granted\_account\_ids *optional* | Limite la réponse aux seuls comptes souhaités en spécifiant une liste d’identifiants séparés par des virgules. Jusqu’à 200 identifiants peuvent être fournis.
Type : string
Exemple : `18ce54aymz3` |
| sort\_by *optional* | Trie selon un attribut pris en charge, par ordre croissant ou décroissant. Voir [Sorting](/fr/x-ads-api/fundamentals/sorting) pour plus d’informations.
Type : string
Exemple : `created_at-asc` |
| custom\_audience\_permission\_ids *optional* | Limite la réponse aux seules autorisations d’audience personnalisée souhaitées en spécifiant une liste d’identifiants séparés par des virgules. Jusqu’à 200 identifiants peuvent être fournis.
Type : string
Exemple : `ri` |
| with\_total\_count *optional* | Inclure l’attribut de réponse `total_count`.
**Remarque** : ce paramètre et `cursor` sont exclusifs.
**Remarque** : les requêtes qui incluent `total_count` auront des limites de taux plus faibles, actuellement fixées à 200 par tranche de 15 minutes.
Type : boolean
Valeur par défaut : `false` Valeurs possibles : `true`, `false` |
**Exemple de requête[](#example-request "Permalien vers ce titre")**
`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/permissions`
**Exemple de réponse[](#example-response "Permalien vers ce titre")**
```
{
"request": {
"params": {
"account_id": "18ce54d4x5t",
"custom_audience_id": "1nmth"
}
},
"next_cursor": null,
"data": [
{
"custom_audience_id": "1nmth",
"permission_level": "READ_ONLY",
"id": "ri",
"created_at": "2017-06-08T23:17:59Z",
"granted_account_id": "18ce54aymz3",
"updated_at": "2017-06-08T23:17:59Z",
"deleted": false
}
]
}
```
#### POST accounts/:account\_id/custom\_audiences/:custom\_audience\_id/permissions[](#post-accounts-account-id-custom-audiences-custom-audience-id-permissions "Permalink to this headline")
Créer un nouvel objet d’autorisation permettant de partager l’audience spécifiée avec un compte donné.
**Remarque** : la création ou la modification des autorisations pour une audience personnalisée nécessite que l’audience soit détenue par le compte qui tente de modifier ces 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 une audience donnée.
**Remarque** : les audiences ne peuvent être partagées qu’entre des comptes publicitaires appartenant à la même entreprise ou si le compte publicitaire qui détient l’audience dispose de la fonctionnalité de compte `SHARE_AUDIENCE_OUTSIDE_BUSINESS`.
**Resource URL[](#resource-url "Permalink to this headline")**
`https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions`
**Parameters[](#parameters "Permalink to this headline")**
| Name | Description |
| :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | 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 Advertiser API, à l’exception de [GET accounts](/fr/x-ads-api/campaign-management#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* | Type d’accès à l’audience personnalisée que `granted_account_id` doit avoir.
Type : enum
Valeurs possibles : `READ_ONLY`, `READ_WRITE` |
| custom\_audience\_id *required* | Référence à l’audience personnalisée utilisée dans la requête.
Type : string
Exemple : `2906h` |
**Example Request[](#example-request "Permalink to this headline")**
```
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h/permissions?granted_account_id=18ce54aymz3&permission_level=READ_ONLY
```
**Exemple de réponse[](#example-response "Permalink to this headline")**
```
{
"request": {
"params": {
"account_id": "18ce54d4x5t",
"granted_account_id": "18ce54aymz3",
"permission_level": "READ_ONLY",
"custom_audience_id": "2906h"
}
},
"data": {
"custom_audience_id": "2906h",
"permission_level": "READ_ONLY",
"id": "14m",
"created_at": "2017-09-12T23:49:34Z",
"granted_account_id": "18ce54aymz3",
"updated_at": "2017-09-12T23:49:34Z",
"deleted": false
}
}
```
#### DELETE accounts/:account\_id/custom\_audiences/:custom\_audience\_id/permissions/:custom\_audience\_permission\_id[](#delete-accounts-account-id-custom-audiences-custom-audience-id-permissions-custom-audience-permission-id "Permalien vers ce titre")
Révoque l’autorisation de partage de la Custom Audience spécifiée.
**Remarque** : la création ou la modification des autorisations pour une Custom Audience nécessite que l’audience appartienne au compte qui tente de modifier ces 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 une audience donnée.
Une fois révoquée, nous garantissons que le compte à qui l’accès a été accordé (`granted_account_id`) ne pourra plus cibler l’audience dans de futures campagnes. Les campagnes existantes continueront à s’exécuter avec les audiences partagées ; les campagnes ne s’arrêtent pas et l’audience n’est pas supprimée de la campagne. Il n’est pas possible de copier cette campagne après la révocation de l’autorisation de partage d’audience.
**URL de la ressource[](#resource-url "Permalien vers ce titre")**
`https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions/:custom_audience_permission_id`
**Paramètres[](#parameters "Permalien vers ce titre")**
| 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 Advertiser API, à l’exception de [GET accounts](/fr/x-ads-api/campaign-management#accounts). Le compte spécifié doit être associé à l’utilisateur authentifié.
Type: string
Example: `18ce54d4x5t` |
| custom\_audience\_id *required* | Une référence à la Custom Audience sur laquelle porte la requête.
Type: string
Example: `1nmth` |
| custom\_audience\_permission\_id *required* | Une référence à l’autorisation de Custom Audience sur laquelle porte la requête.
Type: string
Example: `ri` |
**Exemple de requête[](#example-request "Permalien vers ce titre")**
`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/permissions/ri`
**Exemple de réponse[](#example-response "Permalien vers ce titre")**
```
{
"request": {
"params": {
"account_id": "18ce54d4x5t",
"custom_audience_permission_id": "ri",
"custom_audience_id": "1nmth"
}
},
"data": {
"custom_audience_id": "1nmth",
"permission_level": "READ_ONLY",
"id": "ri",
"created_at": "2017-06-08T23:17:59Z",
"granted_account_id": "18ce54aymz3",
"updated_at": "2017-08-30T18:29:35Z",
"deleted": true
}
}
```
### Audiences personnalisées
#### GET accounts/:account\_id/custom\_audiences[](#get-accounts-account-id-custom-audiences "Permalien vers ce titre")
Récupérer les détails de certaines ou de toutes les audiences personnalisées associées au compte actuel.
**Resource URL[](#resource-url "Permalien vers ce titre")**
`https://ads-api.x.com/12/accounts/:account_id/custom_audiences`
**Parameters[](#parameters "Permalien vers ce titre")**
| Name | Description |
| :-------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | 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](/fr/x-ads-api/campaign-management#accounts). Le compte spécifié doit être associé à l’utilisateur authentifié.
Type: string
Exemple: `18ce54d4x5t` |
| count *optional* | Indique le nombre d’enregistrements à récupérer par requête distincte.
Type: int
Valeur par défaut: `200` Min, max: `1`, `1000` |
| cursor *optional* | Indique un curseur pour obtenir la page suivante de résultats. Consultez [Pagination](/fr/x-ads-api/introduction) pour plus d’informations.
Type: string
Exemple: `8x7v00oow` |
| permission\_scope *optional* | Permet de filtrer la réponse sur les listes que vous possédez ou celles qui ont été partagées avec vous. Par défaut, sans spécifier ce paramètre, vous ne verrez que les audiences que vous possédez.
Type: enum
Valeur par défaut: `OWNER` Valeurs possibles: `OWNER`, `SHARED` |
| q *optional* | Requête optionnelle permettant de restreindre la ressource par `name`.
**Note** : effectue une correspondance de préfixe insensible à la casse.
Type: string
Longueur min, max: `1`, `255` |
| sort\_by *optional* | Trie selon un attribut pris en charge, par ordre croissant ou décroissant. Consultez [Sorting](/fr/x-ads-api/fundamentals/sorting) pour plus d’informations.
Type: string
Exemple: `created_at-asc` |
| custom\_audience\_ids *optional* | Restreint 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
Exemple: `1nmth` |
| with\_deleted *optional* | Inclut les résultats supprimés dans votre requête.
Type: boolean
Valeur par défaut: `false` Valeurs possibles: `true`, `false` |
| with\_total\_count *optional* | Inclut 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 tranche de 15 minutes.
#### GET accounts/:account\_id/custom\_audiences/:custom\_audience\_id[](#get-accounts-account-id-custom-audiences-custom-audience-id "Permalink to this headline")
Récupérer des Custom Audiences spécifiques associées au compte actuel.
**URL de la ressource[](#resource-url "Permalink to this headline")**
`https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id`
**Paramètres[](#parameters "Permalink to this headline")**
| Nom | Description |
| :------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | Identifiant du compte concerné. 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](/fr/x-ads-api/campaign-management#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 avec laquelle vous opérez dans la requête.
Type : string
Exemple : `2906h` |
| with\_deleted *optional* | Inclure les résultats supprimés dans votre requête.
#### POST accounts/:account\_id/custom\_audiences[](#post-accounts-account-id-custom-audiences "Permalien vers ce titre")
Crée une nouvelle Custom Audience factice associée au compte actuel.
**URL de la ressource[](#resource-url "Permalien vers ce titre")**
`https://ads-api.x.com/12/accounts/:account_id/custom_audiences`
**Paramètres[](#parameters "Permalien vers ce titre")**
| Nom | 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](/fr/x-ads-api/campaign-management#accounts). Le compte spécifié doit être associé à l’utilisateur authentifié.
Type: string
Exemple : `18ce54d4x5t` |
| name *required* | Le nom d’affichage de cette audience. Une valeur de nom unique doit être utilisée. Le non‑respect de cette contrainte entraînera une erreur.
Type: string
Exemple : `ads api users` |
| description *optional* | Une description de cette audience.
Type: string
Exemple : `Collection of all users of the Ads API` |
**Exemple de requête[](#example-request "Permalien vers ce titre")**
`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences?name=developers`
**Exemple de réponse[](#example-response "Permalien vers ce titre")**
```
{
"data": {
"targetable": false,
"name": "developers",
"targetable_types": [
"CRM",
"EXCLUDED_CRM"
],
"audience_type": "CRM",
"description": null,
"permission_level": "READ_WRITE",
"owner_account_id": "18ce54d4x5t",
"id": "2906h",
"reasons_not_targetable": [
"PROCESSING",
"TOO_SMALL"
],
"created_at": "2017-08-22T23:34:26Z",
"updated_at": "2017-08-22T23:34:26Z",
"partner_source": "OTHER",
"deleted": false,
"audience_size": null
},
"request": {
"params": {
"account_id": "18ce54d4x5t",
"name": "developers"
}
}
}
```
#### PUT accounts/:account\_id/custom\_audiences/:custom\_audience\_id[](#put-accounts-account-id-custom-audiences-custom-audience-id "Permalien vers ce titre")
Met à jour la Custom Audience spécifique associée au compte actuel.
**Resource URL[](#resource-url "Permalien vers ce titre")**
`https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id`
**Parameters[](#parameters "Permalien vers ce titre")**
| Name | Description |
| :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | Identifiant du compte utilisé. 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’Advertiser API à l’exception de [GET accounts](/fr/x-ads-api/campaign-management#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 que vous utilisez dans la requête.
Type : string
Exemple : `2906h` |
| name *optional* | 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
Exemple : `ads api users` |
| description *optional* | Description de cette audience.
Type : string
Exemple : `Collection of all users of the Ads API` |
**Example Request[](#example-request "Permalien vers ce titre")**
`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h?name=developers_changed`
**Example Response[](#example-response "Permalien vers ce titre")**
```
{
"data": {
"targetable": false,
"name": "developers_changed",
"targetable_types": [
"CRM",
"EXCLUDED_CRM"
],
"audience_type": "CRM",
"description": null,
"permission_level": "READ_WRITE",
"is_owner": true,
"id": "2906h",
"reasons_not_targetable": [
"PROCESSING",
"TOO_SMALL"
],
"created_at": "2017-08-22T23:34:26Z",
"updated_at": "2017-08-22T23:34:26Z",
"partner_source": "OTHER",
"deleted": false,
"audience_size": null
},
"request": {
"params": {
"account_id": "18ce54d4x5t",
"name": "developers_changed"
}
}
}
```
#### POST batch/accounts/:account\_id/custom\_audiences[](#post-batch-accounts-account-id-custom-audiences "Permalien vers ce titre")
Permet la création par lot de Custom Audiences. Consultez la page [Présentation des Custom Audiences](/fr/x-ads-api/audiences) pour plus d’informations sur les audiences.
**Remarque :** Cet endpoint de lot est actuellement en **bêta fermée** et disponible pour un nombre limité d’annonceurs. Pendant cette période de bêta, seules les Flexible Audiences basées sur des audiences mobiles personnalisées peuvent être créées.
**Requêtes par lot**
* 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 lot é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 lot**
Les réponses de l’API par lot renvoient une collection ordonnée d’éléments. Pour le reste, elles sont identiques en termes de structure à leurs endpoints correspondants pour un seul élément.
**Erreurs de lot**
* Les erreurs au niveau de la requête (par ex. taille maximale de lot dépassée) apparaissent dans la réponse sous l’objet `errors`.
* Les erreurs au niveau des éléments (par ex. paramètre obligatoire manquant) apparaissent 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.
* Un maximum de 10 nœuds feuille de Custom Audiences peut être utilisé pour créer une Flexible Audience.
**URL de ressource[](#resource-url "Permalien vers ce titre")**
`https://ads-api.x.com/12/batch/accounts/:account_id/custom_audiences`
**Paramètres[](#parameters "Permalien vers ce titre")**
| 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](/fr/x-ads-api/campaign-management#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
Valeurs possibles : `FLEXIBLE`, `MOBILE_AUDIENCE` |
| child\_segments *required* | Un tableau contenant des 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. Le non-respect de cette règle entraînera une erreur.
Type: string
Example: `my_flexible_audience_name` |
| operation\_type *required* | Le type d’opération appliqué à chaque élément.
Type: enum
Valeurs possibles : `Create`, `Update`, `Delete` |
| boolean\_operator *sometimes required* | La relation logique entre les segments enfants dans leur objet parent (contenant). Obligatoire si `child_segments` n’est pas vide pour l’objet parent.
Type: enum
Valeurs possibles : `AND`, `OR` |
| lookback\_window *sometimes required* | Une valeur entière indiquant l’intervalle de jours pendant lequel l’utilisateur a effectué l’action spécifique et a été qualifié pour la Custom Audience donnée.
Type: int
Valeurs possibles : `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, dans la fenêtre de lookback, la fréquence à laquelle l’utilisateur a effectué l’action spécifique et a été qualifié pour la Custom Audience donnée.
Type: int
Valeur par défaut : `1` |
| frequency\_comparator *optional* | Le comparateur appliqué à la `frequency` passée dans la requête.
**Remarque** : Dans les valeurs ci-dessous, `GTE` signifie greater than or equal (supérieur ou égal), `LT` signifie less than (inférieur), etc.
Type: string
Valeurs possibles : `NUM_GTE`, `NUM_GT`, `NUM_EQ`, `NUM_LTE`, `NUM_LT` Valeur par défaut : `NUM_GTE` |
| negate *optional* | Négation du segment, qui est ainsi exclu de la combinaison.
#### DELETE accounts/:account\_id/custom\_audiences/:custom\_audience\_id[](#delete-accounts-account-id-custom-audiences-custom-audience-id "Permalink to this headline")
Supprime l’Audience personnalisée spécifiée appartenant au compte actuel.
**URL de la ressource[](#resource-url "Permalink to this headline")**
`https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id`
**Paramètres[](#parameters "Permalink to this headline")**
| 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 Advertiser API, à l’exception de [GET accounts](/fr/x-ads-api/campaign-management#accounts). Le compte spécifié doit être associé à l’utilisateur authentifié.
Type: string
Exemple : `18ce54d4x5t` |
| custom\_audience\_id *required* | Une référence à l’Audience personnalisée que vous utilisez dans la requête.
Type: string
Exemple : `2906h` |
**Exemple de requête[](#example-request "Permalink to this headline")**
`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h`
**Exemple de réponse[](#example-response "Permalink to this headline")**
```
{
"data": {
"targetable": false,
"name": "developers",
"targetable_types": [
"CRM",
"EXCLUDED_CRM"
],
"audience_type": "CRM",
"description": null,
"permission_level": "READ_WRITE",
"owner_account_id": "18ce54d4x5t",
"id": "2906h",
"reasons_not_targetable": [
"TOO_SMALL"
],
"created_at": "2017-08-22T23:34:26Z",
"updated_at": "2017-08-30T18:09:00Z",
"partner_source": "OTHER",
"deleted": true,
"audience_size": null
},
"request": {
"params": {
"custom_audience_id": "2906h",
"account_id": "18ce54d4x5t"
}
}
}
```
### Listes d’exclusion de contact
#### GET accounts/:account\_id/do\_not\_reach\_lists[](#get-accounts-account-id-do-not-reach-lists "Permalink to this headline")
Récupérer 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’au maximum une liste Do Not Reach
**URL de la ressource[](#resource-url "Permalink to this headline")**
`https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists`
**Paramètres[](#parameters "Permalink to this headline")**
| Name | Description |
| :------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | 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](/fr/x-ads-api/campaign-management#accounts). Le compte spécifié doit être associé à l’utilisateur authentifié.
Type : string
Exemple : `18ce54d4x5t` |
| with\_deleted *optional* | Inclure les résultats supprimés dans votre requête.
Type : boolean
Valeur par défaut : `false` Valeurs possibles : `true`, `false` |
**Exemple de requête[](#example-request "Permalink to this headline")**
`GET https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists`
**Exemple de réponse[](#example-response "Permalink to this headline")**
```
{
"request": {
"params": {
"account_id": "18ce54bgxky"
}
},
"next_cursor": null,
"data": [
{
"targetable": false,
"name": "Do Not Reach List",
"description": "test DNRL",
"id": "4kzrq",
"reasons_not_targetable": [
"TOO_SMALL"
],
"created_at": "2021-10-28T22:09:29Z",
"list_size": null,
"updated_at": "2021-11-04T03:33:06Z",
"deleted": false
}
]
}
```
#### POST accounts/:account\_id/do\_not\_reach\_lists[](#post-accounts-account-id-do-not-reach-lists "Permalien vers ce titre")
Créer une nouvelle Liste Ne Pas Contacter associée au compte actuel.
**Remarque** : un `account_id` ne peut avoir au maximum qu’une seule Liste Ne Pas Contacter
**URL de ressource[](#resource-url "Permalien vers ce titre")**
`https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists`
**Paramètres[](#parameters "Permalien vers ce titre")**
| Nom | 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](/fr/x-ads-api/campaign-management#accounts). Le compte spécifié doit être associé à l’utilisateur authentifié.
Type : string
Exemple : `18ce54d4x5t` |
| description *optional* | Une description pour cette audience.
Type : string
Exemple : `A list of users to exclude` |
**Exemple de requête[](#example-request "Permalien vers ce titre")**
`POST https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists?description=A list of users to exclude`
**Exemple de réponse[](#example-response "Permalien vers ce titre")**
```
{
"request": {
"params": {
"description": "A list of users to exclude",
"account_id": "18ce54bgxky"
}
},
"data": {
"targetable": false,
"name": "Do Not Reach List",
"description": "A list of users to exclude",
"id": "4ofrq",
"reasons_not_targetable": [
"PROCESSING",
"TOO_SMALL"
],
"created_at": "2022-02-08T23:02:48Z",
"list_size": null,
"updated_at": "2022-02-08T23:02:48Z",
"deleted": false
}
}
```
#### POST batch/accounts/:account\_id/do\_not\_reach\_lists/:do\_not\_reach\_list\_id/users[](#post-batch-accounts-account-id-do-not-reach-lists-do-not-reach-list-id-users "Permalien vers ce titre")
Cet endpoint permet d’ajouter, de mettre à jour et de supprimer des utilisateurs dans 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 en utilisant `SHA256` et [normalisées](/fr/x-ads-api/audiences#e-mail-normalization).
**Remarques**
* Un `account_id` ne peut être associé 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 à compter 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
* La Do Not Reach List ne supprime pas les utilisateurs d’une ou de toutes les audiences personnalisées du compte, mais agit comme un ciblage d’exclusion pour toutes les campagnes diffusées pour le compte
**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 seul 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, pour les erreurs comme pour les succès, préservent l’ordre des éléments de la requête initiale.
**Réponses par lots**
La réponse renvoyée par l’Ads API contient deux champs, un `success_count` et un `total_count`. Ces valeurs doivent toujours être égales, et elles correspondent au nombre d’enregistrements dans 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 condition d’erreur nécessitant une nouvelle tentative.
**Erreurs par lots**
* Les erreurs au niveau de la requête (par ex. taille de lot maximale dépassée) sont indiquées dans la réponse dans l’objet `errors`.
* Les erreurs au niveau des éléments (par ex. paramètres obligatoires manquants) sont indiquées dans la réponse dans l’objet `operation_errors`.
* L’index de l’erreur dans `operation_errors` fait référence à l’index de l’élément en entrée, avec le message d’erreur correspondant
**URL de la ressource[](#resource-url "Permalien vers ce titre")**
`https://ads-api.x.com/12/batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users`
**Paramètres[](#parameters "Permalien vers ce titre")**
| 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’Advertiser API, à l’exception de [GET accounts](/fr/x-ads-api/campaign-management#accounts). Le compte spécifié doit être associé à l’utilisateur authentifié.
Type: string
Example: `18ce54d4x5t` |
| do\_not\_reach\_list\_id *required* | Une référence à la Do Not Reach List avec laquelle vous opérez dans la requête
Type: string
Example: `2906h` |
| operation\_type *required* | Le type d’opération par groupe `users` en cours d’exécution.
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 individuel.
Type: JSON |
| expires\_at *optional* | L’heure UTC à laquelle l’association ou les associations d’utilisateurs doivent expirer. L’heure spécifiée doit être postérieure à la valeur de l’horodatage actuel. Exprimée au format [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). Par défaut : 13 mois à partir de l’horodatage actuel.
Type: string
Example: `2017-07-05T07:00:00Z` |
Compte tenu de l’approche multi-clés pour l’objet `users`, chaque élément de cet objet est documenté ci-dessous :
| Name | 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.
#### DELETE accounts/:account\_id/do\_not\_reach\_lists/:do\_not\_reach\_list\_id[](#delete-accounts-account-id-do-not-reach-lists-do-not-reach-list-id "Permalink to this headline")
Supprimer la Do Not Reach List spécifiée appartenant au compte en cours.
**URL de la ressource[](#resource-url "Permalink to this headline")**
`https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id`
**Paramètres[](#parameters "Permalink to this headline")**
Aucun
**Exemple de requête[](#example-request "Permalink to this headline")**
`DELETE https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists/4ofrp`
**Exemple de réponse[](#example-response "Permalink to this headline")**
```
{
"request": {
"params": {
"do_not_reach_list_id": "4ofrp",
"account_id": "18ce54bgxky"
}
},
"data": {
"targetable": false,
"name": "Do Not Reach List",
"description": null,
"id": "4ofrp",
"reasons_not_targetable": [
"PROCESSING",
"TOO_SMALL"
],
"created_at": "2022-02-08T23:02:07Z",
"list_size": null,
"updated_at": "2022-02-08T23:02:21Z",
"deleted": true
}
}
```
Les partenaires d’audience ou API fournissent une liste d’identifiants hachés et X effectue un appariement et produit des segments qui sont mis à disposition pour l’achat média sur X. Les partenaires peuvent créer ces audiences avec l’[Audience API](/fr/x-ads-api/audiences).
**Fonctionnement**
**Web**
Nous proposons un processus standard de mise en correspondance de cookies lorsque nous travaillons avec des partenaires d’audience MPP afin d’identifier les segments à cibler pour l’achat média sur X. En outre, les annonceurs peuvent configurer une balise [X Web Event Tag](/fr/x-ads-api/measurement/web-conversions#web-event-tags) pour collecter les données des utilisateurs de leur site web et créer une audience personnalisée correspondante.
**Étapes de configuration**
![]()
**Fonctionnement**
**Mobile**
Veuillez consulter [l’article de blog Custom Audiences from Mobile Apps](https://blog.x.com/2014/introducing-tailored-audiences-from-mobile-apps) pour plus de détails.
**Flexible**
Les [audiences flexibles](/fr/x-ads-api/audiences) donnent aux annonceurs la possibilité de créer et d’enregistrer des combinaisons d’audiences basées sur des audiences personnalisées existantes ou des sous-ensembles d’audiences personnalisées existantes. Les sous-ensembles des membres d’une audience personnalisée peuvent être ciblés en fonction de la récence et de la fréquence des interactions.
**Cas d’utilisation restreints pour les audiences personnalisées**
[En savoir plus sur les restrictions](https://developer.x.com/en/developer-terms/more-on-restricted-use-cases "Read more about restrictions")
**Information**
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 (ID Sync) 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 utilisateur X pouvant être utilisées pour le ciblage. Ces audiences personnalisées seront mises à disposition sur le @handle spécifique de l’annonceur, indiqué par le libellé lors de la configuration de campagne Custom Audiences Web sur ads.x.com.
X fournira le pixel sécurisé qui pourra être intégré dans les balises et sur les sites des partenaires afin de faire correspondre les ID (`p_user_ids`) aux ID utilisateur 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](https://analytics.x.com/i/adsct?p\_user\_id=xyz\&p\_id=123)
**`p_user_id`** - xyz représente l’ID utilisateur du 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) pouvant être utilisés pour ingérer régulièrement le fichier de ciblage. Un exemple d’endpoint HTTPS se présentera comme suit :
```
https://