Gestion des campagnes

​

API pour les annonceurs

Programmez des campagnes et gérez des publicités sur X par voie programmatique grâce à cette suite d’API.

​

Que pouvez-vous promouvoir ?

​

Publicités sponsorisées

• Les Publicités sponsorisées sont des annonces classiques achetées par des annonceurs souhaitant toucher un groupe plus large d’utilisateurs ou stimuler l’engagement de leurs abonnés existants.
• Les Publicités sponsorisées portent clairement la mention Sponsorisé lorsqu’un annonceur paie pour leur diffusion sur X. Par ailleurs, elles se comportent comme des publicités classiques et peuvent être repartagées, recevoir des réponses, des likes, etc. Elles suivent des règles de diffusion standard et sont créées à l’aide de POST statuses/update.
• Tweets « Promoted-only », créés via POST accounts/:account_id/tweet, peuvent être utilisés dans des campagnes de Promoted Tweets, mais ne seront pas diffusés auprès des abonnés ni affichés sur la timeline publique. Pour obtenir la liste des tweets « promoted-only » d’un compte donné, utilisez GET accounts/:account_id/scoped_timeline.

​

Comptes sponsorisés

• Les Comptes sponsorisés font partie de « Who to Follow », qui suggère des comptes que les utilisateurs ne suivent pas encore et qui pourraient les intéresser. Les Comptes sponsorisés permettent de faire découvrir un éventail encore plus large de comptes susceptibles de plaire.
• Les Comptes sponsorisés pour la Timeline associent un Tweet sponsorisé à une campagne de Compte sponsorisé et s’affichent dans les timelines des utilisateurs.

Les Tendances sponsorisées ne sont pas disponibles dans l’X Ads API.

​

Campagnes et groupes d’annonces (line items)

Les campagnes définissent le calendrier et le budget d’une annonce. L’annonceur spécifie un budget quotidien et global. La campagne peut être liée à une heure de début et de fin spécifiques ou se poursuivre en continu jusqu’à épuisement du budget. Le budget provient de l’un des instruments de financement du compte publicitaire. Les identifiants de campagne (:campaign_id) sont la représentation en base 36 de la valeur en base 10 affichée dans l’interface X Ads.

Les comptes publicitaires sont limités à un maximum de 200 campagnes actives. Cette limite peut être portée manuellement à 4 000 campagnes actives par le X Account Manager de l’annonceur, sur demande. Une campagne est considérée comme active jusqu’à son heure de fin ou sa suppression. Les campagnes mises en pause sont considérées actives jusqu’à leurs heures de fin prévues.

Les line items dépensent le budget défini par une campagne. Les line items regroupent l’enchère par engagement, le Tweet ou le compte à promouvoir, ainsi que les règles de ciblage.

​

Analytics

La X Ads API propose un ensemble d’endpoints d’analytics pour suivre et optimiser les performances publicitaires. Veuillez consulter Analytics et Analytics Best Practices pour plus d’informations.

Pour la métrique de facturation, les data peuvent ne pas être finalisées avant trois jours après l’événement. Avant ce délai, les data doivent être considérées comme spéculatives. Le nombre facturable final sera toujours inférieur au montant spéculatif. Le nombre facturable est corrigé pour le spam et le trafic de faible qualité associé. Voir Timezones pour d’autres considérations concernant le temps.

​

Création d’une campagne - étape par étape

L’exemple suivant suppose que vous avez installé, configuré et autorisé votre App et votre utilisateur à l’aide de twurl. twurl est un outil en ligne de commande, dans l’esprit de cURL, qui gère efficacement l’authentification OAuth de X. twurl est un excellent outil pour tester et déboguer rapidement les fonctionnalités de la X Ads API (et de l’API REST). Pour afficher les en-têtes complets de la requête et de la réponse, utilisez -t pour tracer l’appel, ce qui est à peu près équivalent à l’option -v de cURL.

Pour cet exemple, nous allons créer une campagne Promoted Ads ciblée par mot-clé.

1. Récupérez l’id du compte.

twurl -H ads-api.x.com /9/accounts/

{
  "request": {
    "params": {
    }
  },
  "data": [
    {
      "name": "Compte de test pour @AdsAPI",
      "timezone": "America/Los_Angeles",
      "timezone_switch_at": null,
      "id": "xxxxxx",
      "created_at": "2014-03-09T00:41:49Z",
      "salt": "f9f9d5a5f23075c618da5eb1d1a9df57",
      "updated_at": "2015-01-29T00:41:49Z",
      "approval_status": "ACCEPTED",
      "deleted": false
    }
  ],
  "data_type": "account",
  "total_count": 1,
  "next_cursor": null
}

2. Récupérez l’id de l’instrument de financement.

Appelez l’API GET accounts/:account_id/funding_instruments en utilisant l’id du compte récupéré dans la commande précédente.

twurl -H ads-api.x.com /9/accounts/xxxxxx/funding_instruments

{
  "data": [
    {
      "cancelled": true,
      "created_at": "2014-03-09T00:41:49Z",
      "credit_limit_local_micro": null,
      "currency": "USD",
      "deleted": false,
      "description": null,
      "end_time": null,
      "funded_amount_local_micro": null,
      "id": "yyyy",
      "type": null,
      "updated_at": "2014-05-29T00:41:49Z"
    }
  ],
  "data_type": "funding_instrument",
  "next_cursor": null,
  "request": {
    "params": {
      "account_id": "xxxxxx"
    }
  },
  "total_count": 1
}

3. Créez une campagne et associez-la à l’instrument de financement.

Indiquez une date/heure de début et un budget pour la campagne. Pour cet exemple, nous utiliserons un budget de 500 $et une limite quotidienne de 50$.

twurl -H ads-api.x.com -d "funding_instrument_id=yyyy&name=Ma Première Campagne&total_budget_amount_local_micro=500000000&daily_budget_amount_local_micro=50000000" /9/accounts/xxxxxx/campaigns

{
  "data": {
    "created_at": "2015-02-09T00:00:00Z",
    "currency": "USD",
    "daily_budget_amount_local_micro": 50000000,
    "deleted": false,
    "end_time": null,
    "funding_instrument_id": "yyyy",
    "id": "92ph",
    "name": "Ma première campagne",
    "entity_status": "PAUSED",
    "standard_delivery": true,
    "total_budget_amount_local_micro": 500000000,
    "updated_at": "2015-02-09T00:00:00Z"
  },
  "data_type": "campaign",
  "request": {
    "params": {
      "account_id": "xxxxxx",
      "daily_budget_amount_local_micro": 50000000,
      "funding_instrument_id": "yyyy",
      "name": "Ma première campagne",
      "total_budget_amount_local_micro": 500000000
    }
  }
}

4. Créer un élément de ligne associé à la campagne.

Maintenant que nous avons un id de campagne, nous pouvons créer un élément de ligne à lui associer. L’élément de ligne regroupe le prix d’enchère, le ciblage et la partie créative de la campagne. Pour cet élément de ligne, nous allons promouvoir des tweets avec une enchère de 1,50 $.

twurl -H ads-api.x.com -d "campaign_id=XXXX&bid_amount_local_micro=1500000&product_type=PROMOTED_TWEETS&placements=ALL_ON_TWITTER&objective=ENGAGEMENTS&entity_status=PAUSED" /9/accounts/xxxxxxx/line_items

{
  "data_type": "line_item",
  "data": {
    "bid_type": "MAX",
    "name": "Sans titre",
    "placements": [
      "ALL_ON_TWITTER"
    ],
    "bid_amount_local_micro": 1500000,
    "automatically_select_bid": false,
    "advertiser_domain": null,
    "primary_web_event_tag": null,
    "charge_by": "ENGAGEMENT",
    "product_type": "PROMOTED_TWEETS",
    "bid_unit": "ENGAGEMENT",
    "total_budget_amount_local_micro": null,
    "objective": "ENGAGEMENTS",
    "id": "azjx",
    "entity_status": "PAUSED",
    "optimization": "DEFAULT",
    "categories": [],
    "currency": "USD",
    "created_at": "2015-02-09T00:00:00Z",
    "updated_at": "2015-02-09T00:00:00Z",
    "include_sentiment": "POSITIVE_ONLY",
    "campaign_id": "92ph",
    "deleted": false
  },
  "request": {
    "params": {
      "placements": [
        "ALL_ON_TWITTER"
      ],
      "bid_amount_local_micro": 1500000,
      "product_type": "PROMOTED_TWEETS",
      "entity_status": "PAUSED",
      "account_id": "xxxxxxx",
      "campaign_id": "92ph"
    }
  }
}

5. Créez un profil de ciblage associé à l’élément de ligne.

Une fois l’élément de ligne créé, nous pouvons lui attribuer des critères de ciblage. Nous souhaitons cibler l’expression-clé « grumpy cat » dans la région de la baie de San Francisco. Cela nécessitera une recherche de l’id du lieu et deux requêtes POST vers targeting_criteria.

twurl -H ads-api.x.com "/9/targeting_criteria/locations?location_type=CITIES&q=San Francisco"

{
  "data": [
    {
      "name": "San Francisco-Oakland-San José CA, États-Unis",
      "targeting_type": "LOCATION",
      "targeting_value": "5122804691e5fecc"
    }
  ],
  "data_type": "targeting_criterion",
  "request": {
    "params": {
      "location_type": "CITY",
      "q": "San Francisco"
    }
  }
}

twurl -H ads-api.x.com -X POST -d "line_item_id=yyyy&targeting_type=LOCATION&targeting_value=5122804691e5fecc" /9/accounts/xxxxxx/targeting_criteria

{
  "data": {
    "created_at": "2015-02-09T00:00:15Z",
    "deleted": false,
    "id": "2u3be",
    "line_item_id": "yyyy",
    "name": "San Francisco-Oakland-San Jose CA, US",
    "targeting_type": "LOCATION",
    "targeting_value": "5122804691e5fecc",
    "updated_at": "2013-05-30T21:01:35Z"
  },
  "data_type": "targeting_criterion",
  "request": {
    "params": {
      "account_id": "xxxxxx",
      "line_item_id": "yyyy",
      "targeting_type": "LOCATION",
      "targeting_value": "5122804691e5fecc"
    }
  }
}

twurl -H ads-api.x.com -X POST -d "line_item_id=yyyy&targeting_type=PHRASE_KEYWORD&targeting_value=grumpy cat" /9/accounts/xxxxxx/targeting_criteria

{
  "data": {
    "created_at": "2015-02-09T00:00:20Z",
    "deleted": false,
    "id": "2u3bd",
    "line_item_id": "yyyy",
    "name": "grumpy cat",
    "targeting_type": "PHRASE_KEYWORD",
    "targeting_value": "grumpy cat",
    "updated_at": "2013-05-30T18:05:35Z"
  },
  "data_type": "targeting_criterion",
  "request": {
    "params": {
      "account_id": "xxxxxx",
      "line_item_id": "yyyy",
      "targeting_type": "PHRASE_KEYWORD",
      "targeting_value": "grumpy cat"
    }
  }
}

6. Enfin, réactivez l’élément de ligne.

twurl -H ads-api.x.com -X PUT "/9/accounts/xxxxxx/line_items/yyyy/?entity_status=ACTIVE"

{
  "data_type": "line_item",
  "data": {
    "bid_type": "MAX",
    "name": "grumpy cat",
    "placements": [],
    "bid_amount_local_micro": 1500000,
    "automatically_select_bid": false,
    "advertiser_domain": null,
    "primary_web_event_tag": null,
    "charge_by": "ENGAGEMENT",
    "product_type": "PROMOTED_TWEETS",
    "bid_unit": "ENGAGEMENT",
    "total_budget_amount_local_micro": null,
    "objective": "ENGAGEMENTS",
    "id": "yyyy",
    "entity_status": "ACTIVE",
    "optimization": "DEFAULT",
    "categories": [],
    "currency": "USD",
    "created_at": "2015-02-09T00:00:20Z",
    "updated_at": "2015-02-09T00:00:20Z",
    "include_sentiment": "POSITIVE_ONLY",
    "campaign_id": "dy1f",
    "deleted": false
  },
  "request": {
    "params": {
      "line_item_id": "yyyy",
      "entity_status": "ACTIVE",
      "account_id": "xxxxxx"
    }
  }
}

C’est tout ! Nous avons désormais une campagne « Promoted Tweets in Timelines » active, ciblée et financée, actuellement en cours.

​

Campagnes basées sur un objectif

Les campagnes basées sur un objectif et la tarification associée permettent aux annonceurs de payer pour les actions alignées sur leurs objectifs marketing. Pour les activer, définissez l’objective approprié sur les line items.

Le paramètre utilisé sur les endpoints d’écriture des line items et renvoyé sur les endpoints de lecture est objective. Ce champ peut actuellement prendre les valeurs suivantes :

• APP_ENGAGEMENTS
• APP_INSTALLS
• FOLLOWERS
• ENGAGEMENTS
• REACH
• VIDEO_VIEWS
• PREROLL_VIEWS
• WEBSITE_CLICKS

Les objectifs influencent la façon dont nous optimisons les campagnes dans nos enchères et la manière dont nous les facturons. Nous proposons une tarification basée sur l’objectif, par exemple CPAC pour APP_ENGAGEMENTS, CPAC ou CPI pour APP_INSTALLS, CPLC pour WEBSITE_CLICKS, CPF pour FOLLOWERS, CPE pour ENGAGEMENTS et CPM pour REACH.

Les campagnes de promotion d’applications mobiles doivent comporter l’objectif APP_ENGAGEMENTS ou APP_INSTALLS.

Remarque : des line items avec des objectifs différents ne sont pas autorisés au sein d’une même campagne.

Objectif de campagne	Objectif API	Média dans les Tweets	Modèle de tarification
Réengagements d’app	APP_ENGAGEMENTS	Carte de téléchargement d’app (image ou vidéo) requise.	CPAC
Installations d’app	APP_INSTALLS	Carte de téléchargement d’app (image ou vidéo) requise.	CPAC ou CPI (défini via charge_by)
Portée	REACH	Aucune restriction.	CPM
Abonnés	FOLLOWERS	Tweet non requis, mais recommandé. Aucune restriction de média pour les Tweets des campagnes Abonnés, bien que nous recommandions des Tweets uniquement textuels. Plus d’informations	CPF
Engagements	ENGAGEMENTS	Aucune restriction.	CPE
Vues vidéo	VIDEO_VIEWS	Carte de conversation vidéo, vidéo ou GIF requis.	CPV ou coût par vue 3 s/100 %
Vues pre-roll	PREROLL_VIEWS	Vidéo requise.	CPV ou coût par vue 3 s/100 %
Clics vers site web	WEBSITE_CLICKS	Carte de site web recommandée, mais non requise. Le Tweet doit contenir soit une carte de site web, soit un lien vers un site web (pas les deux).	CPLC

​

Instruments de financement

Les instruments de financement constituent la source du budget de campagne. Ils ne peuvent pas être créés via la X Ads API ; ils doivent déjà avoir été configurés par le responsable de compte de l’annonceur chez X (pour les lignes de crédit) ou via ads.x.com (pour les cartes de crédit) pour être disponibles.

Pour obtenir la liste de tous les funding_instruments d’un compte, consultez GET accounts/:account_id/funding_instruments ainsi que GET accounts/:account_id/funding_instruments/:funding_instrument_id pour les détails d’un instrument spécifique.

​

Attributs de l’instrument de financement

Descriptif : account_id, id de l’instrument de financement, type de l’instrument de financement, description et io_header (ID d’en-tête d’ordre d’insertion). Notez qu’un même io_header peut être associé à plusieurs instruments de financement.

Capacité de financement : able_to_fund et reasons_not_able_to_fund.

Temps : created_at, updated_at, start_time et end_time représentés par une chaîne au format “%Y-%m-%dT%l:%M:%S%z”.

Statut booléen : paused, deleted et cancelled (vrai ou faux).

Financier : currency (format ISO-4217), credit_limit_local_micro, credit_remaining_local_micro et funded_amount_local_micro. La valeur d’une devise est exprimée en micros. Pour l’USD, 5,50 $ est encodé sous la forme 5.50*1e6, soit 5 500 000. Pour représenter une « valeur entière », vous devez multiplier la valeur en micros locale par 1e6 (1_000_000) pour toutes les devises.

​

Détails des attributs

credit_limit_local_micro n’est valide que pour les instruments de financement de type CREDIT_CARD ou CREDIT_LINE et représente la limite de crédit de cet instrument.

funded_amount_local_micro n’est valide que pour les instruments de financement de type INSERTION_ORDER et représente le budget alloué.

credit_remaining_local_micro est valide pour les instruments de financement de type CREDIT_LINE et AGENCY_CREDIT_LINE. Il correspond à credit_limit_local_micro moins le montant déjà dépensé sur cet instrument de financement. Il ne correspond pas à la différence entre funded_amount_local_micro et le montant dépensé. Nous distinguons la limite de crédit du montant financé, car ils reflètent des méthodes de financement sous-jacentes et des accords de dépense différents que nous avons avec les annonceurs.

​

Types d’instruments de financement

Cartes de crédit

Généralement utilisées par les annonceurs en libre-service (sans gestionnaire de compte).

Lignes de crédit

Elles prennent la forme d’ordres d’insertion (IO) et sont définies par les gestionnaires de compte.

Lignes de crédit multi-handle

Les annonceurs peuvent financer des campagnes sur plusieurs handles avec ce type de ligne de crédit. Cette fonctionnalité est activée par leur X Account Manager, qui associe les différents @handles à une ligne de crédit spécifique.

Par exemple, @NikeSB et @NikeFuel peuvent tous deux avoir accès à la ligne de crédit @Nike. Cet instrument de financement est disponible comme les autres. Vous récupérez les data en envoyant une requête GET à l’endpoint funding_instrument. Voici un exemple de réponse (notez le type CREDIT_LINE).

      GET https://ads-api.x.com/5/accounts/a0b1c3/funding_instruments

{
    "request": {
        "params": {
            "account_id": "a0b1c3"
        }
    },
    "data": [
        {
            "start_time": "2013-05-30T04:00:00Z",
            "description": "FakeNike - Ligne de crédit",
            "credit_limit_local_micro": 150000000000,
            "end_time": null,
            "cancelled": false,
            "id": "i1234",
            "paused": false,
            "account_id": "a0b1c3",
            "reasons_not_able_to_fund": [],
            "io_header": null,
            "currency": "USD",
            "funded_amount_local_micro": 0,
            "created_at": "2013-05-30T18:16:38Z",
            "type": "CREDIT_LINE",
            "able_to_fund": true,
            "updated_at": "2013-05-30T18:16:38Z",
            "credit_remaining_local_micro": 123661919751,
            "deleted": false,
        }
    ],
    "data_type": "funding_instrument",
    "total_count": 1,
    "next_cursor": null
}

La seule particularité de cet instrument de financement réside dans son type et dans le fait qu’il est disponible pour tous les comptes qui y sont associés. Bien entendu, le crédit restant est affecté par toutes les campagnes financées par cet instrument, sur l’ensemble des comptes qui le partagent. Les détails sur les comptes associés à une ligne de crédit donnée ne sont pas disponibles via l’API (ni via ads.x.com).

Pour plus d’informations sur les valeurs d’énumération des Funding Instruments, veuillez cliquer ici.

​

Ciblage

Le ciblage est un concept clé de la X Ads API. Il est défini au niveau de la ligne et les options varient selon les emplacements. Pour définir de nouveaux critères de ciblage, utilisez POST accounts/:account_id/targeting_criteria et PUT accounts/:account_id/targeting_criteria pour les mettre à jour.

Utilisez GET accounts/:account_id/line_items pour obtenir la liste de toutes les lignes et GET accounts/:account_id/line_items/:line_item_id pour récupérer une ligne spécifique.

​

Options de ciblage par emplacement

Les produits Promoted Tweets et Promoted Accounts peuvent être diffusés sur différents emplacements. Les Promoted Trends (PTr) ne sont pas disponibles via l’API.

Pour les combinaisons d’emplacements possibles, consultez l’endpoint GET line_items/placements. Chaque emplacement propose différentes options de ciblage. La localisation, la plateforme et le genre sont disponibles pour tous. Les autres options dépendent du type d’emplacement.

• X Search: Ciblage par âge, Appareils, Événements, Genre, Types de mots-clés (tous), Langue, Localisations, Activation du réseau, Opérateurs réseau, Plateforme, Version de la plateforme, Audiences personnalisées, Wi‑Fi uniquement
• X Timeline: Ciblage par âge, Appareils, Événements, Abonnés de, Similaire aux abonnés de, Genre, Centres d’intérêt, Langue, Localisations, Activation du réseau, Opérateurs réseau, Types de mots-clés non exacts, Types d’audiences partenaires, Plateforme, Version de la plateforme, Types de reciblage, Audiences personnalisées, Types de ciblage TV, Wi‑Fi uniquement
• X Profiles & Tweet Details: Ciblage par âge, Appareils, Événements, Abonnés de, Similaire aux abonnés de, Genre, Centres d’intérêt, Langue, Localisations, Activation du réseau, Opérateurs réseau, Types de mots-clés non exacts, Types d’audiences partenaires, Plateforme, Version de la plateforme, Types de reciblage, Audiences personnalisées, Types de ciblage TV, Wi‑Fi uniquement

​

Comprendre les types de ciblage

Ciblage par âge : Ciblez les utilisateurs selon des tranches d’âge spécifiques. Une liste des énumérations de tranches d’âge est disponible sur la page Enumerations.

Événements : Spécifiez un événement pour le ciblage. Un seul événement peut être utilisé pour le ciblage (par élément de campagne). Utilisez l’endpoint GET targeting_criteria/events pour trouver les événements disponibles pour le ciblage.

Genre : Ciblez les hommes (1) ou les femmes (2). Laissez null pour toucher tout le monde.

Catégories d’App installées : utilisez ce type de ciblage pour cibler les utilisateurs en fonction des catégories d’apps qu’ils ont installées ou pour lesquelles ils ont indiqué un intérêt. Voir GET targeting_criteria/app_store_categories.

Intérêts : Ciblez les utilisateurs par centres d’intérêt. Récupérez la liste des intérêts via GET targeting_criteria/interests. Vous pouvez cibler jusqu’à 100 intérêts.

Abonnés de : Ciblez les abonnés de tout utilisateur entièrement promouvable pour le compte actuel (notez qu’actuellement, le titulaire principal du compte est le seul utilisateur entièrement promouvable de ce compte). GET accounts/:account_id/promotable_users pour obtenir une liste d’utilisateurs promouvables.

Similaires aux abonnés de : Ciblez des personnes ayant les mêmes intérêts que les abonnés d’utilisateurs spécifiques. Vous pouvez utiliser jusqu’à 100 utilisateurs.

Emplacements : Spécifiez jusqu’à 2 000 emplacements à cibler. Obtenez la liste via GET targeting_criteria/locations. Des exigences supplémentaires s’appliquent aux publicités ciblant certains pays. Voir Country Targeting and Display Requirements pour plus d’informations.

Mots-clés : Les options de ciblage par mot-clé varient selon le type d’emplacement. Vous pouvez utiliser jusqu’à 1 000 mots-clés pour le ciblage (par élément de campagne). Voir la section sur les types de mots-clés pour les options.

Ciblage par langue : Ciblez les utilisateurs qui comprennent des langues spécifiques.

Ciblage par opérateur de réseau mobile : Permet aux annonceurs de cibler les utilisateurs selon l’opérateur mobile, en utilisant le type de ciblage NETWORK_OPERATOR depuis GET targeting_criteria/network_operators.

Ciblage des nouveaux appareils mobiles : Touchez des utilisateurs selon la date à laquelle ils ont accédé à X pour la première fois via leur appareil, en utilisant le type de ciblage NETWORK_ACTIVATION_DURATION avec un operator_type de LT pour « inférieur à » et GTE pour « supérieur ou égal à ».

Platforms, Platform Versions, Devices et Wifi-Only : Permet le ciblage d’appareils mobiles selon divers axes. Platforms est un type de ciblage de haut niveau qui peut couvrir de larges catégories de téléphones. Des exemples de valeurs sont iOS et Android. Devices permet de cibler les utilisateurs d’appareils mobiles spécifiques, par exemple l’iPhone 5s, le Nexus 4 ou le Samsung Galaxy Note. Platform versions permet de cibler les utilisateurs de versions spécifiques de systèmes d’exploitation mobiles, jusqu’à la version de correctif. Exemples : iOS 7.1 et Android 4.4. Wifi-Only permet de cibler uniquement les utilisateurs qui utilisent leurs appareils sur un réseau Wi‑Fi ; si ce paramètre n’est pas défini, les utilisateurs se connectant via l’opérateur comme en Wi‑Fi seront ciblés.

• Les utilisateurs peuvent cibler des plateformes et des appareils s’il n’y a pas de chevauchement. Je peux cibler BlackBerry comme plateforme et iPad Air comme appareil simultanément.
• Les utilisateurs peuvent cibler des appareils et des versions d’OS simultanément. Je peux cibler iPad Air et iOS >= 7.0.
• Les utilisateurs ne peuvent pas cibler des plateformes plus larges que des appareils. Je ne peux pas cibler iOS et iPad Air.

[Tailored Audiences]/x-ads-api/audiences: Atteignez des utilisateurs via un partenaire publicitaire approuvé pour cibler des groupes de clients et interagir avec eux sur X.

Ciblage TV

Ciblage d’émissions TV : atteignez les personnes qui interagissent avec des programmes TV spécifiques. Ce critère de ciblage peut être configuré pour s’appliquer en continu tant qu’une campagne est active avec le type de ciblage TV_SHOW. Utilisez les endpoints GET targeting_criteria/tv_markets et GET targeting_criteria/tv_shows pour déterminer les émissions TV disponibles.

Reciblage des engageurs de Tweet

Le reciblage des engageurs de Tweet permet aux annonceurs de cibler, sur plusieurs appareils, des audiences qui ont déjà été exposées à leurs Tweets sponsorisés ou organiques sur X, ou qui ont interagi avec ceux-ci. Avec ce ciblage, les annonceurs peuvent relancer les personnes ayant vu ou interagi avec le contenu d’un annonceur sur X et les plus susceptibles de poursuivre l’engagement ou de convertir à la suite de messages ou d’offres ultérieurs. Les utilisateurs deviennent éligibles au ciblage dans les minutes suivant l’exposition ou l’engagement et le restent jusqu’à 90 jours après pour les engagements et 30 jours pour les expositions.

Types de ciblage des engageurs de Tweet :

• ENGAGEMENT_TYPE, qui accepte IMPRESSION ou ENGAGEMENT comme valeur de ciblage. Cela précise si vous souhaitez cibler des utilisateurs exposés (IMPRESSION) ou des utilisateurs ayant interagi (ENGAGEMENT).
• CAMPAIGN_ENGAGEMENT utilise un id de campagne comme valeur de ciblage. Les utilisateurs qui ont interagi avec cette campagne ou y ont été exposés (selon ENGAGEMENT_TYPE) seront ciblés.
• USER_ENGAGEMENT, qui utilise l’id de l’utilisateur promu comme valeur de ciblage afin d’atteindre les utilisateurs exposés au contenu organique d’un annonceur ou ayant interagi avec celui-ci (selon ENGAGEMENT_TYPE). Il doit s’agir de l’id de l’utilisateur promu associé au compte Ads.

Note : ENGAGEMENT_TYPE est requis en plus d’au moins une valeur valide CAMPAIGN_ENGAGEMENT ou USER_ENGAGEMENT. Les deux types de ciblage des engageurs de Tweet peuvent être présents et plusieurs campagnes peuvent être ciblées sur une même ligne d’élément.

Ciblage des visionneurs de vidéo : Le ciblage des visionneurs de vidéo s’appuie sur le ciblage des engageurs de Tweet pour permettre aux annonceurs de toucher des audiences ayant déjà regardé une partie ou la totalité d’une vidéo sur X. Les annonceurs peuvent cibler des vidéos organiques, des vidéos sponsorisées ou les deux. Les vidéos sponsorisées ne sont pas limitées aux campagnes ou lignes d’élément ayant pour objectif les vues vidéo.

Types de ciblage des visionneurs de vidéo :

• VIDEO_VIEW pour les utilisateurs qui ont cliqué pour lancer la vidéo ou ont regardé 3 secondes de lecture automatique
• VIDEO_VIEW_PARTIAL pour les utilisateurs qui ont regardé 50 % de la vidéo
• VIDEO_VIEW_COMPLETE pour les utilisateurs qui ont regardé au moins 95 % de la vidéo

Comme pour le ciblage des engageurs de Tweet, un ou les deux éléments suivants doivent également être présents dans les critères de ciblage de la ligne d’élément lorsque ENGAGEMENT_TYPE est utilisé :

• CAMPAIGN_ENGAGEMENT utilise un id de campagne comme valeur de ciblage. Les utilisateurs qui ont regardé une vidéo (selon ENGAGEMENT_TYPE) dans cette campagne seront ciblés.
• USER_ENGAGEMENT, qui utilise l’id de l’utilisateur promu comme valeur de ciblage pour toucher les utilisateurs ayant regardé une vidéo (selon ENGAGEMENT_TYPE) dans le contenu organique d’un annonceur. Il doit s’agir de l’id de l’utilisateur promu associé au compte Ads.

Types de mots-clés

Consultez notre document d’aide sur le ciblage par mots-clés pour une vue d’ensemble conceptuelle.

• Large (valeur par défaut) : fait correspondre tous les mots, indépendamment de l’ordre. Insensible à la casse, aux pluriels ou au temps. Sera automatiquement étendu lorsque possible (p. ex. « car repair » correspondra également à « automobile fix »). Si vous souhaitez cibler sans expansion, ajoutez un signe + avant les mots-clés, comme « +boat +jet ». L’utilisation de mots-clés sans le + correspond par défaut au Large Match.
• Non ordonné (obsolète) : fait correspondre tous les mots, indépendamment de l’ordre. Insensible à la casse, aux pluriels ou au temps.
• Expression : fait correspondre exactement la chaîne de mots-clés, d’autres mots peuvent être présents.
• Exact : fait correspondre exactement la chaîne de mots-clés, aucun autre.
• Négatif : évite de faire correspondre les recherches qui incluent tous ces mots-clés quelque part dans la query, quel que soit l’ordre dans lequel ils sont écrits, même si d’autres mots sont présents.
• Expression négative : évite de faire correspondre les recherches qui incluent exactement cette chaîne de mots-clés quelque part dans la query, même si d’autres mots sont présents.
• Exact négatif : évite de faire correspondre les recherches qui correspondent exactement à ces mots-clés et ne contiennent aucun autre mot.  

Ciblage par emoji

Le ciblage par emoji est pris en charge via le ciblage par mots-clés. Pour utiliser le ciblage par emoji, créez simplement un ciblage par mots-clés à partir des points de code Unicode représentant cet emoji, comme U+1F602 (xF0x9Fx98x82 en UTF‑8) pour l’emoji « visage avec des larmes de joie » (😂). Les emoji que nous acceptons peuvent être vérifiés à l’aide de la liste twemoji. Le ciblage d’un emoji englobe toutes ses variantes.

Pour un récapitulatif de toutes les valeurs, avec les champs obligatoires/facultatifs et les détails spécifiques pour chacune, voir PUT accounts/:account_id/targeting_criteria.

​

Combinaisons de critères de ciblage

Workflow de campagne mis à jour

Créez des campagnes qui ciblent largement à l’aide de critères de zone géographique, de genre, de langue et d’appareil/plateforme. Les annonceurs peuvent ensuite combiner ce ciblage large avec des critères supplémentaires (p. ex., centres d’intérêt, mots-clés, abonnés, audiences personnalisées, TV). Si aucun critère de ciblage n’est spécifié pour un élément de ligne, celui-ci ciblera tous les utilisateurs dans le monde entier.

Types « principaux »	Autres types
Abonnés	Lieux
Audiences personnalisées	Genre
Centres d’intérêt	Langues
Mots-clés	Appareils et plateformes
TV	Âge

Les critères de ciblage seront combinés pour votre groupe de publicités comme suit :

• Les types de ciblage « principaux » seront mis en ∪ (c’est‑à‑dire réunis par une union logique).
• Les autres types de ciblage seront combinés avec AND.
• Les types identiques seront combinés avec OR.

Quelques exemples

En un coup d’œil : [(Abonnés) ∪ (Audiences personnalisées) ∪ (Centres d’intérêt) ∪ (Mots-clés)] AND (Lieu) AND (Genre) AND (Langues) AND (Appareils et plateformes)

Un exemple géographique :

Disons que nous voulons qu’un groupe de publicités pour notre campagne applique le ciblage suivant :

• utilisateurs X aux États‑Unis, en Angleterre et au Canada (Lieu)
• qui sont des femmes (Genre)
• provenant d’une liste d’audiences personnalisées (« principaux »)
• avec des mots-clés (« principaux »)

Les critères de ciblage seront :

[US OR GB OR CA] AND [Female] AND [Tailored Audiences ∪ Keyword]

​

Exemples supplémentaires

• Sélectionner Sexe et Zone géographique sans primaire : (Male) AND (US OR GB)
• Sélectionner Sexe, Zone géographique, Centre d’intérêt : (Female) AND (CA) AND (Computers OR Technology OR Startups)
• Sélectionner Sexe, Zone géographique, Centre d’intérêt, Tailored Audiences, Keywords : (Male) AND (GB) AND (Cars ∪ Tailored Audiences for CRM ∪ autocross)

​

Cadence du budget

Les annonceurs disposent désormais d’un meilleur contrôle sur la vitesse à laquelle leurs budgets quotidiens sont dépensés pour vos campagnes de Tweet sponsorisé et de Compte. Activer la diffusion standard, l’option par défaut, garantit un rythme de dépense uniforme tout au long de la journée.

En désactivant la diffusion standard, nous diffuserons des impressions et générerons des interactions aussi rapidement que possible jusqu’à épuisement de votre budget quotidien, ce qui peut survenir assez tôt dans la journée selon le ciblage et la concurrence. C’est ce que l’on appelle la diffusion accélérée.

Pour commencer

La diffusion standard est l’option par défaut pour toutes les campagnes, aucune action n’est donc requise sauf si vous souhaitez la désactiver. Pour dépenser votre budget quotidien sur une campagne aussi rapidement que possible, définissez le paramètre standard_delivery sur false afin de passer en diffusion accélérée (voir GET accounts/:account_id/campaigns).

Remarques

• Le « jour » correspond au fuseau horaire du compte annonceur X (p. ex. America/Los_Angeles).
• Les premiers résultats indiquent que la diffusion standard améliore l’eCPE/CPF pour les annonceurs, avec une couverture plus régulière tout au long de la journée.

Pour plus d’informations sur les budgets et la cadence de diffusion, veuillez consulter la FAQ sur les enchères et les offres.

​

Enchères ciblées

Gestion de campagne

​

Stratégie d’enchères

Nous avons introduit le concept de Stratégie d’enchères pour simplifier le processus de création de campagnes et réduire la confusion liée aux combinaisons de plusieurs paramètres.

Toutes les combinaisons de paramètres précédentes (marquées comme héritées) peuvent être reproduites en définissant un paramètre d’objectif équivalent. Pour plus d’informations, consultez l’annonce ici.

À titre d’exemple :

Objectif de campagne	Hérité	X Ads API v10+
Installations d’App	bid_type = AUTO bid_unit = APP_INSTALLS charge_by = APP_CLICKS	goal = APP_INSTALLS bid_strategy = AUTO
Clics vers le site web	bid_type = TARGET (Remarque : bid_unit n’était pas nécessaire pour certains objectifs de campagne)	bid_strategy = TARGET

​

Enchères au coût cible

Avec les enchères au coût cible, vous pouvez définir un coût cible que vous souhaitez payer et la plateforme X Ads optimisera les performances de votre campagne tout en restant proche de votre coût cible, ou en dessous.

Cette fonctionnalité vous offre la flexibilité d’atteindre des utilisateurs particulièrement susceptibles d’effectuer l’action souhaitée (comme un clic sur un lien, un lead ou un follow), tout en conservant la maîtrise des coûts. C’est une fonctionnalité puissante pour les annonceurs qui souhaitent davantage d’options de configuration et d’optimisation de campagne (y compris des options d’enchères).

Pour les items d’inventaire avec des objectifs de campagne compatibles, nous avons introduit un nouveau mécanisme de tarification de l’enchère qui vous permet de définir un coût cible à payer. Notre plateforme publicitaire enchérit dynamiquement en votre nom pour vous aider à générer plus de résultats, tout en s’efforçant de maintenir votre coût moyen dans les 20 % de la cible spécifiée. Le paramètre bid_strategy sur les items peut être défini sur la valeur TARGET pour activer les enchères au coût cible sur des objectifs de campagne pertinents, tels que :

• WEBSITE_CLICKS
• WEBSITE_CONVERSIONS 
• APP_INSTALLS 
• APP_ENGAGEMENTS
• REACH

​

Exigences de ciblage par pays et d’affichage

Gestion des campagnes

Les exigences spécifiques à chaque pays en matière de ciblage et d’affichage sont détaillées sur cette page. Tous les partenaires doivent s’y conformer.

​

Russie

Les règles publicitaires de X interdisent aux annonceurs de cibler la Russie avec des publicités qui ne sont pas en russe. Lorsque vos utilisateurs ciblent spécifiquement la Russie, vous devez afficher l’avertissement suivant à leur intention :

Les publicités ciblant la Russie doivent être en russe.

​

Instruments de financement gérés par le partenaire

Le processus d’intégration configure un compte ads.x.com pour le compte X, que le partenaire peut gérer via la X Ads API, et dont les dépenses publicitaires sont facturées au partenaire.  

​

Configuration initiale du partenaire

Le processus de configuration initiale d’un nouveau partenaire PMFI Ads API peut prendre jusqu’à 3 semaines à compter de l’échange des informations requises. Les éléments suivants doivent être partagés avec vos contacts techniques chez X, ainsi qu’avec le contact X qui gère l’intégration avec le partenaire, afin de lancer le processus :

• Le partenaire doit partager sa clé publique PGP/GPG. Une clé secrète partagée doit être échangée entre le partenaire Ads API et X. Elle sera utilisée pour vérifier les données durant le parcours d’onboarding.
• Le app_id ou le consumer_secret de la X App qui sera utilisée pour l’accès à la X Ads API. Vous pouvez consulter et modifier vos X Apps existantes via le tableau de bord des apps si vous êtes connecté à votre compte X sur developer.x.com. Si vous devez créer une X App, vous devrez disposer d’un compte développeur approuvé. X autorise une app pour la production et le sandbox, ainsi qu’une app facultative pour un accès réservé au sandbox. La X App doit être créée sur un compte X d’entreprise, contrôlé par le partenaire.  

​

Parcours d’intégration des annonceurs

Le parcours d’intégration des annonceurs s’effectue via un navigateur web de la manière suivante :

1. L’utilisateur démarre le parcours d’intégration sur le site du partenaire et saisit le handle qu’il souhaite intégrer.
2. Le partenaire redirige l’utilisateur vers une URL sur ads.x.com avec une charge utile signée. Cette charge utile contient l’API app_id du partenaire, le user_id X du handle X à intégrer, ainsi qu’une URL de rappel et d’autres fields documentés ci‑dessous.
3. L’utilisateur est invité à se connecter à ads.x.com via la page de connexion standard de x.com.
4. Une fois connecté, le processus d’intégration est lancé. Cette étape inclut la revue des publicités, la validation du compte et d’autres vérifications.
5. Lorsque toutes les tâches d’intégration sont terminées, l’utilisateur est redirigé vers l’URL de rappel fournie par le partenaire Ads API, avec une charge utile indiquant la réussite ou l’échec. Cela inclut le processus d’autorisation en 3 étapes.  

​

Charge utile de redirection pour l’onboarding

URL de redirection :

https://ads.x.com/link_managed_account

L’URL de redirection sera appelée avec les paramètres suivants :

Nom	Type	Description
callback_url	Chaîne encodée en URL	l’utilisateur sera redirigé vers cette URL une fois le processus de liaison du compte terminé, quel qu’en soit le résultat. Voir la section « URL de redirection du partenaire » pour les détails du protocole
client_app_id	entier	id de l’App cliente de la X API, utilisé pour identifier le partenaire gestionnaire
promotable_user_id	entier	user_id X du @handle dont les promotions doivent être gérées par le partenaire gestionnaire. Utilisé pour vérifier qu’il s’agit du même utilisateur qui se connecte à ads.x.com pour finaliser la liaison
fi_description	Chaîne encodée en URL (255 caractères max)	nom de l’instrument de financement. Celui-ci sera affiché dans le champ description de l’API lors de la récupération de l’instrument de financement. Si une description funding_instrument est fournie, l’instrument de financement existant sera mis en pause et un nouvel instrument de financement de partenaire géré sera configuré (si un instrument existe avec le même nom, rien ne se passera)
timezone	Chaîne, au format Area/Location	Fuseau horaire utilisé pour déterminer le jour auquel s’appliquent les budgets quotidiens et dans lequel les frais seront agrégés
currency	Code de devise ISO 4217	Devise utilisée pour saisir les enchères et dans laquelle les frais seront facturés
country	Code pays ISO 3166-1 alpha 2	Pays de facturation du compte
signature	Code binaire encodé en base64 et encodé en URL, comme expliqué ci-dessous	signature combinant un secret partagé et les autres paramètres pour vérifier l’authenticité de l’appel ainsi que la validité des paramètres.

​

Charge utile de l’URL de rappel

L’URL de redirection de base est fournie via le paramètre callback_url dans la requête de liaison de compte (voir ci‑dessus). Les paramètres ajoutés par ads.x.com sont :

Name	Type	Description
status	string	OK un compte a été créé ou un compte existant et admissible a été trouvé. ACCOUNT_INELIGIBLE si les contraintes spécifiques au partenaire ne sont pas respectées USER_MISMATCH le compte X utilisé pour se connecter à ads.x.com était différent du promotable_user_id dans la requête de liaison de compte INCOMPLETE_SERVING_BILLING_INFO le fuseau horaire, la devise ou le pays n’ont pas été spécifiés INVALID_COUNTRY une valeur de pays non valide a été fournie INVALID_CURRENCY une valeur de devise non valide a été fournie INVALID_TIMEZONE une valeur de fuseau horaire non valide a été fournie
account_id	URL encoded string	id de compte publicitaire X du compte lié
funding_instrument_id	URL encoded string	ID de l’instrument de financement actif géré par le partenaire
signature	URL encoded, base64 encoded binary code, as explained below	Signature HMAC‑SHA1 encodée en Base64 qui combine un secret partagé et les autres paramètres afin de vérifier l’authenticité de l’appel ainsi que la validité des paramètres. Pour garantir que l’URL de rappel n’est valide que pour le X user_id auquel le processus de liaison de compte est destiné, le X user_id doit être ajouté au secret partagé (avec &) lors de la signature de la requête.

Pour garantir que l’URL de rappel n’est valide que pour le X user_id auquel le processus de liaison de compte est destiné, le X user_id doit être ajouté au secret partagé (avec &) lors de la signature de la requête.  

​

Signature de la requête et des URL de rappel

Afin de garantir que les requêtes vers /link_managed_account et l’URL de rappel sont valides, elles doivent être signées à la source puis vérifiées par le destinataire avant que celui-ci n’agisse. La signature de la requête à l’aide d’un secret partagé entre X et le partenaire gestionnaire garantit que chaque partie n’accepte que les requêtes envoyées par la contrepartie autorisée.

L’algorithme de génération de signature est similaire à celui utilisé par OAuth.

Créez une chaîne de base de signature comme suit :

• Convertissez la méthode HTTP en majuscules et définissez la chaîne de base sur cette valeur.
• Ajoutez le caractère « & » à la chaîne de base.
• Effectuez un encodage pourcentage de l’URL (sans paramètres) et ajoutez-la à la chaîne de base.
• Ajoutez le caractère « & » à la chaîne de base.
• Ajoutez la chaîne de requête encodée en pourcentage, construite comme suit :
• Encodez en pourcentage chaque clé et chaque valeur à signer.
• Triez la liste des paramètres par ordre alphabétique des clés.
• Pour chaque paire clé/valeur (et avec primary_promotable_user_id pour l’URL de redirection du partenaire) :
• Ajoutez la clé encodée en pourcentage à la chaîne de requête.
• Ajoutez le caractère « = » à la chaîne de base.
• Ajoutez la valeur encodée en pourcentage à la chaîne de requête.
• Séparez les paires clé=valeur encodées en pourcentage avec le caractère « & ».
• Utilisez l’algorithme HMAC-SHA1, en prenant comme clé le secret partagé échangé précédemment et comme valeur la chaîne de base, pour générer la signature.
• Encodez en Base64 la sortie de l’étape 2, supprimez le caractère de fin de ligne, encodez en pourcentage la signature générée à l’étape 3 et ajoutez-la à l’URL dans un paramètre signature  

​

Exemples de signature

Signature d’une requête de liaison de compte

URL à signer, en supposant une requête GET :

https://ads.x.com/link_managed_account?callback_url=https%3A%2F%2Fmanagingpartner.com%2Flink_account_callback&client_app_id=12345&fi_description=some%20name&promotable_user_id=1

Cette URL comporte les paramètres suivants :

callback_url = https://managingpartner.com/link_account_callback client_app_id = 12345 fi_description = some name promotable_user_id = 1

La chaîne de base, composée de la méthode HTTP et de l’URL sans paramètres (étapes a à d), est la suivante :

GET https://ads.x.com/link_managed_account

La chaîne de requête, produite par les sous‑étapes de e, est la suivante :

callback_url=https://managingpartner.com/link_account_callback&client_app_id=12345&fi_description=some name&promotable_user_id=1

Notez que les paires clé‑valeur sont triées par nom de clé.

La chaîne de requête encodée en pourcentage est la suivante :

callback_url%3Dhttps%253A%252F%252Fmanagingpartner.com%252Flink_account_callback%26client_app_id%3D12345%26fi_description%3Dsome%2520name%26promotable_user_id%3D1

La chaîne de base complète, combinant les étapes a à d et e :

GET https://ads.x.com/link_managed_account&callback_url%3Dhttps%253A%252F%252Fmanagingpartner.com%252Flink_account_callback%26client_app_id%3D12345%26fi_description%3Dsome%2520name%26promotable_user_id%3D1

À l’aide de l’algorithme hmac-sha1, nous allons signer ceci avec le mot « secret » comme clé. Le résultat est encodé en Base64 et présenté sans le « \n » final (étapes 2 et 3) : KBxQMMSpKRrtg9aw3qxK4fTXvUc=

Cette signature est ensuite ajoutée (encodée en pourcentage) à la fin de l’URL d’origine dans le paramètre de signature (étape 4) :

https://ads.x.com/link_managed_account?callback_url=https%3A%2F%2Fmanagingpartner.com%2Flink_account_callback&client_app_id=12345&fi_description=some%20name&promotable_user_id=1&signature=KBxQMMSpKRrtg9aw3qxK4fTXvUc%3D

Signature d’une URL de redirection partenaire (callback de requête de liaison de compte) L’URL à signer, en supposant une requête GET :

https://managingpartner.com/link_account_callback?status=OK&account_id=ABC&funding_instrument_id=DEF

Cette URL comporte les paramètres suivants :

account_id = ABC, funding_instrument_id = DEF et status = OK

La chaîne de base, composée de la méthode HTTP et de l’URL sans paramètres (étapes a à d), est la suivante :

GET https%3A%2F%2Fmanagingpartner.com%2Flink_account_callback&“

La chaîne de requête, produite par les sous‑étapes de e, est la suivante :

account_id=ABC&funding_instrument_id=DEF&status=OK

La chaîne de requête encodée en pourcentage est la suivante :

account_id%3DABC%26funding_instrument_id%3DDEF%26status%3DOK

La chaîne de base complète, combinant les étapes a à d et e :

GET https%3A%2F%2Fmanagingpartner.com%2Flink_account_callback&account_id%3DABC%26funding_instrument_id%3DDEF%26status%3DOK

À l’aide de l’algorithme hmac-sha1, nous allons signer ceci avec le mot « secret » et l’id utilisateur X pour lequel la requête de liaison d’origine a été effectuée, 1 (promotable_user_id = 1 ci‑dessus), comme clé : « secret&1 ».

Le résultat est encodé en Base64 et présenté sans le « \n » final (étapes 2 et 3) : jDSHDkHJIFXpPLVxtA3a9d4bPjM=

Cette signature est ensuite ajoutée (avec encodage en pourcentage) à la fin de l’URL d’origine, dans le paramètre signature (étape 4) :

https://managingpartner.com/link_account_callback?&status=OK&account_id=ABC&funding_instrument_id=DEF&signature=jDSHDkHJIFXpPLVxtA3a9d4bPjM%3D

​

Utilisation / renouvellement de clé partagée

L’algorithme de signature doit pouvoir s’exécuter avec plusieurs clés. Cela permettra d’utiliser plusieurs clés partagées et de faire tourner ces clés de manière périodique.  

​

création de partner_managed_funding_instrument

Si le paramètre fi_description est fourni et qu’aucun partner_managed_funding_instrument portant le même nom n’existe dans le compte, un nouveau partner_managed_funding_instrument sera créé et tous les partner_managed_funding_instruments existants seront mis en pause.

Si un partner_managed_funding_instrument portant le même nom existe, aucun nouveau ne sera créé.  

​

Répétition des appels du flux d’onboarding / actualisation du jeton

Le flux d’onboarding peut être relancé si l’access token de l’API a été perdu. La mise en œuvre du flux d’onboarding exige que l’utilisateur soit connecté. Si l’utilisateur correspond au promotable_user_id, que le compte publicitaire associé est trouvé et que tout est en ordre, l’utilisateur sera redirigé vers l’URL de rappel et le partenaire pourra lancer le flux OAuth pour obtenir un access token.  

​

Flux d’erreur non redirigeable

Si l’URL de liaison de compte est appelée avec des paramètres invalides, une page similaire à celle affichée dans le flux OAuth lorsque des paramètres invalides ou expirés sont fournis s’affichera pour l’utilisateur.  

​

Mises à jour en continu du PMFI

Une fois l’annonceur intégré, l’instrument de financement ne peut être géré via l’endpoint PUT accounts/:account_id/funding_instruments/:funding_instrument_id que par le partenaire qui l’administre.

​

Emplacements

Plusieurs emplacements peuvent afficher des publicités X. Ceci se définit au niveau de l’élément de campagne (line item) à l’aide du paramètre placements. Les valeurs possibles sont :

• ALL_ON_TWITTER
• PUBLISHER_NETWORK
• TWITTER_PROFILE
• TWITTER_SEARCH
• TWITTER_TIMELINE
• SPOTLIGHT
• TREND

Les champs product_type et objective de l’élément de campagne déterminent les emplacements autorisés. L’endpoint GET line_items/placements permet de récupérer les options d’emplacement valides pour chaque type de produit.

Le tableau suivant répertorie également les combinaisons valides d’emplacement et d’objectif.

Objective	ALL_ON_TWITTER	TWITTER_PROFILE	TWITTER_SEARCH	TWITTER_TIMELINE
APP_ENGAGEMENTS	✔	✔	✔	✔
APP_INSTALLS	✔	✔	✔	✔
REACH	✔	✔	✔	✔
FOLLOWERS	✔	✔	✔	✔
ENGAGEMENTS	✔	✔	✔	✔
VIDEO_VIEWS	✔	✔	✔	✔
PREROLL_VIEWS	✔	✔	✔	✔
WEBSITE_CLICKS	✔	✔	✔	✔

Remarque : Il n’est pas possible de spécifier uniquement l’emplacement TWITTER_PROFILE.

Remarque : TWITTER_SEARCH nécessite un ciblage par mots-clés.

Remarque : L’objectif REACH doit inclure l’emplacement TWITTER_TIMELINE. Il peut inclure ALL_ON_TWITTER, toute combinaison d’emplacements comprenant TWITTER_TIMELINE, ou TWITTER_TIMELINE seul.

​

FAQ sur les groupes d’annonces

Ce document rassemble les questions fréquemment posées au sujet des groupes d’annonces dans la X Ads API.

​

Qu’est-ce qu’un groupe d’annonces ?

Les groupes d’annonces, appelés « line items » dans la X Ads API, se trouvent sous les campagnes et servent à cibler et à enchérir sur un ensemble d’utilisateurs de X. Les annonceurs promeuvent des Tweets ou des médias (par exemple, des vidéos diffusées en tant que publicités In-stream) en les associant à un line item.

​

Comment créer un groupe d’annonces ?

Les groupes d’annonces sont créés en appelant POST accounts/:account_id/line_items plusieurs fois pour le même id de campagne, en conservant le ciblage (éventuellement complètement différent) et les Tweets associés à ces éléments de ligne. Il existe une limite de 100 éléments de ligne par campagne et une limite de 200 campagnes actives par compte publicitaire. Tous types de campagnes confondus, il y a une limite de 8 000 éléments de ligne actifs par compte publicitaire.

​

Pourquoi ajouter la prise en charge des groupes d’annonces ?

Les groupes d’annonces sont conçus pour faciliter l’organisation, l’optimisation et la gestion des campagnes par les annonceurs.

L’intérêt des groupes d’annonces est de comparer et de piloter différentes stratégies d’enchères, de budget, de création et de ciblage. Lorsqu’on associe plusieurs Promoted Tweets à une même ligne d’achat, l’enchère sélectionne le meilleur Tweet de ce groupe, puis le meilleur Tweet pour cette campagne parmi toutes les lignes d’achat. Si vous avez plusieurs groupes d’annonces avec un seul Tweet chacun, le système sélectionnera effectivement, pour ce groupe d’annonces, le Tweet qui a le plus de chances d’obtenir de meilleures performances.

L’utilisation des groupes d’annonces permet à un annonceur de décomposer le ciblage et les enchères en un nombre beaucoup plus important de combinaisons possibles et, de manière générale, d’organiser le ciblage en groupes logiques.

Les outils de la X Ads API, en particulier, pourraient être conçus autour de règles d’optimisation finement réglées au niveau des groupes d’annonces, ce qui serait plus difficile à réaliser par des modifications manuelles en raison de l’ampleur des combinaisons de lignes d’achat et de créations.

​

Quelle est la relation entre le budget d’un élément de ligne et le budget de la campagne dans une campagne Groupes d’annonces ?

Le total_budget_amount_local_micro d’un élément de ligne ne peut pas dépasser le budget total de sa campagne parente. De même, la valeur bid_amount_local_micro de l’élément de ligne ne doit pas dépasser daily_budget_amount_local_micro ou total_budget_amount_local_micro de la campagne parente. Un paramétrage incorrect de ces valeurs peut entraîner la mise en pause de la campagne globale et la rendre non diffusable.

Notez que le budget total de la campagne peut être inférieur à la somme des budgets de ses éléments de ligne enfants, et que la répartition du budget entre les éléments de ligne relève en partie de l’outil X Ads API, qui peut l’optimiser et l’ajuster de manière efficace, car les performances quotidiennes du ciblage (élément de ligne) peuvent varier considérablement d’un jour à l’autre en raison de la nature en temps réel de X.

​

Les groupes d’annonces offrent-ils de meilleures performances que des éléments de campagne isolés ?

Les performances d’une campagne dépendent de nombreux facteurs et, au final, le Tweet est l’élément déterminant. Un élément de campagne conditionne même l’éligibilité d’un Tweet à être diffusé à un utilisateur.

Les éléments de campagne qui ciblent les mêmes ensembles d’utilisateurs présentent un chevauchement d’audience. Il est recommandé de réduire ce chevauchement de ciblage entre éléments afin d’identifier clairement les ensembles d’utilisateurs les plus performants.

​

Guides

​

Objectif Vues vidéo en pré‑roll

Le guide suivant décrit les étapes nécessaires pour configurer une campagne PREROLL_VIEWS sur la X Ads API. De manière générale, ces campagnes se répartissent en deux types : Catégories sélectionnées et Catégories de contenu (appelées Catégories standard dans l’interface Ads).  

​

Endpoints requis

• Chunked media upload (pour le téléversement de vidéos)
• POST accounts/:account_id/media_library (pour associer la vidéo au compte publicitaire)
• POST accounts/:account_id/campaigns (créer une campagne)
• GET content_categories (pour obtenir la correspondance entre les catégories de contenu et les catégories IAB)
• GET accounts/:account_id/curated_categories
• GET publishers
• POST accounts/:account_id/line_item_curated_categories
• POST accounts/:account_id/line_items (créer un groupe d’annonces)
• POST accounts/:account_id/media_creatives (pour associer la vidéo au groupe d’annonces)
• POST accounts/:account_id/preroll_call_to_action (définir l’appel à l’action et l’URL de redirection)
• POST batch/accounts/:account_id/targeting_criteria (ciblage)

​

Étapes

​

Charger la vidéo

Le chargement de la vidéo se fait en 2 étapes :

​

Importer le média vidéo

Tout d’abord, à l’aide de l’endpoint Chunked media upload, vous allez importer la vidéo sur X pour traitement. Vous devez transmettre media_category=amplify_video lors de l’INIT initial avec cet endpoint. Vous importerez la vidéo par segments. Une fois que le STATUS renvoie un state de succeeded, vous pouvez poursuivre avec les étapes suivantes. Plus d’informations sur l’import de médias via l’endpoint par segments sont disponibles dans notre aperçu de Promoted Video.

​

Ajouter la vidéo au compte publicitaire

Une fois que l’état renvoyé par la commande STATUS est succeeded, utilisez la valeur media_key retournée par cet endpoint pour ajouter la vidéo à la médiathèque de l’annonceur, via l’endpoint POST accounts/:account_id/media_library.

POST https://ads-api.x.com/8/55w3kv/media\_library?media\_key=3_931236738554519552

{
 "request": {
   "params": {
     "account_id": "55w3kv",
     "media\_key": "3\_931236738554519552"
   }
 },
 "data": {
   "tweeted": false,
   "name": null,
   "file_name": null,
   "media\_url": "https://video.twimg.com/amplify\_video/1059840836186165250/vid/568x320/Gr2l1fB1X7xotKwC.mp4?tag=8",
   "media\_category": "AMPLIFY\_VIDEO",
   "media\_key": "3\_931236738554519552",
   "created_at": "2017-11-16T19:05:14Z",
   "media\_status": "TRANSCODE\_COMPLETED",
   "media_id": 931236738554519552,
   "media_type": "VIDEO",
   "updated_at": "2017-11-16T19:05:23Z",
   "deleted": false
 }
}

​

Configurer la campagne

​

Création de campagne

Créez la campagne et l’élément de campagne/groupe d’annonces. Les éléments de campagne doivent être créés avec objective défini sur VIDEO_VIEWS_PREROLL et product_type sur MEDIA. Le paramètre categories doit également être défini sur les catégories d’activité de l’annonceur appropriées.

POST https://ads-api.x.com/8/accounts/55w3kv/campaigns?name=test-curated-categories-api&funding\_instrument\_id=103hp9&start\_time=2021-02-10&entity\_status=PAUSED&daily\_budget\_amount\_local\_micro=55000000

{
  "request": {
    "params": {
      "name": "test-curated-categories-api",
      "start_time": "2021-02-10T00:00:00Z",
      "daily\_budget\_amount\_local\_micro": 55000000,
      "funding\_instrument\_id": "103hp9",
      "entity_status": "PAUSED",
      "account_id": "55w3kv"
    }
  },
  "data": {
    "name": "test-curated-categories-api",
    "start_time": "2021-02-10T00:00:00Z",
    "reasons\_not\_servable": \[
      "EXPIRED",
      "PAUSED\_BY\_ADVERTISER",
      "FUNDING_PROBLEM"
    \],
    "servable": false,
    "purchase\_order\_number": null,
    "effective_status": "PAUSED",
    "daily\_budget\_amount\_local\_micro": 55000000,
    "end_time": null,
    "funding\_instrument\_id": "103hp9",
    "duration\_in\_days": null,
    "standard_delivery": true,
    "total\_budget\_amount\_local\_micro": null,
    "id": "f2rp3",
    "entity_status": "PAUSED",
    "frequency_cap": null,
    "currency": "USD",
    "created_at": "2021-02-08T23:55:38Z",
    "updated_at": "2021-02-08T23:55:38Z",
    "deleted": false
  }
}

​

Création d’élément de ligne

Les éléments de ligne doivent définir le paramètre categories avec l’ensemble approprié de catégories IAB, récupérées via l’endpoint GET content_categories. Chaque catégorie de contenu correspond à une ou plusieurs catégories IAB.

Pour utiliser ces valeurs, les partenaires doivent sélectionner une catégorie de contenu appropriée et utiliser l’ensemble complet des iab_categories renvoyé dans la réponse afin de définir le paramètre categories sur l’endpoint des éléments de ligne. Toute application partielle des iab_categories entraînera l’application de l’ensemble du groupe à l’élément de ligne. Par exemple,

GET https://ads-api.x.com/8/advertiser\_business\_categories

{
  "request": {
    "params": {}
  },
  "next_cursor": null,
  "data": \[
    {
      "id": "1jl",
      "name": "Biens de grande consommation",
      "iab_categories": \[
        "IAB9-26",
        "IAB9-18",
        "IAB9-29",
        "IAB9-1",
        "IAB9-8",
        "IAB9-22",
        "IAB6",
        "IAB9-5",
        "IAB9-12",
        "IAB9-11",
        "IAB9-23",
        "IAB9-14",
        "IAB4",
        "IAB9-25",
        "IAB9-17",
        "IAB23",
        "IAB9-24",
        "IAB9-13",
        "IAB16",
        "IAB9-4",
        "IAB9-9",
        "IAB9-20",
        "IAB22",
        "IAB9-28",
        "IAB9-27",
        "IAB9-16",
        "IAB9-31",
        "IAB9-3",
        "IAB9-19",
        "IAB10",
        "IAB9-2",
        "IAB9-6",
        "IAB9-21",
        "IAB9-10",
        "IAB9-15"
      \]
    },
    {
      "id": "1jm",
      "name": "Santé et pharmacie",
      "iab_categories": \[
        "IAB7"
      \]
    },
    {
      "id": "1jn",
      "name": "Alcool",
      "iab_categories": \[
        "IAB8-5",
        "IAB8-18"
      \]
    },
    {
      "id": "1jo",
      "name": "Restauration",
      "iab_categories": \[
        "IAB8-10",
        "IAB8-8",
        "IAB8-7",
        "IAB8-15",
        "IAB8-3",
        "IAB8-4",
        "IAB8-1",
        "IAB8-16",
        "IAB8-12",
        "IAB8-13",
        "IAB8-17",
        "IAB8-11",
        "IAB8-6",
        "IAB8-9",
        "IAB8-2",
        "IAB8-14"
      \]
    },
    {
      "id": "1jp",
      "name": "Services financiers",
      "iab_categories": \[
        "IAB3",
        "IAB13",
        "IAB21"
      \]
    },
    {
      "id": "1jq",
      "name": "Commerce de détail",
      "iab_categories": \[
        "IAB18"
      \]
    },
    {
      "id": "1jr",
      "name": "Voyage",
      "iab_categories": \[
        "IAB20"
      \]
    },
    {
      "id": "1js",
      "name": "Jeux vidéo",
      "iab_categories": \[
        "IAB9-30"
      \]
    },
    {
      "id": "1jt",
      "name": "Technologie",
      "iab_categories": \[
        "IAB19-22",
        "IAB19-13",
        "IAB19-4",
        "IAB19-33",
        "IAB19-26",
        "IAB19-3",
        "IAB19-16",
        "IAB19-9",
        "IAB19-32",
        "IAB19-25",
        "IAB19-30",
        "IAB19-36",
        "IAB19-21",
        "IAB5",
        "IAB19-12",
        "IAB19-28",
        "IAB19-17",
        "IAB19-8",
        "IAB19-7",
        "IAB19-24",
        "IAB15",
        "IAB19-11",
        "IAB19-31",
        "IAB19-20",
        "IAB19-15",
        "IAB19-1",
        "IAB19-35",
        "IAB19-29",
        "IAB19-34",
        "IAB19-23",
        "IAB19-2",
        "IAB19-5",
        "IAB19-14",
        "IAB19-27",
        "IAB19-10",
        "IAB19-19"
      \]
    },
    {
      "id": "1ju",
      "name": "Télécommunications",
      "iab_categories": \[
        "IAB19-6",
        "IAB19-18"
      \]
    },
    {
      "id": "1jv",
      "name": "Automobile",
      "iab_categories": \[
        "IAB2"
      \]
    },
    {
      "id": "1jw",
      "name": "Médias et divertissement",
      "iab_categories": \[
        "IAB14-8",
        "IAB14-4",
        "IAB1-5",
        "IAB14-7",
        "IAB1-7",
        "IAB17",
        "IAB14-3",
        "IAB1-1",
        "IAB12",
        "IAB1-6",
        "IAB25-1",
        "IAB1-2",
        "IAB14-2",
        "IAB14-6",
        "IAB1-3",
        "IAB1-4",
        "IAB14-5"
      \]
    },
    {
      "id": "1jx",
      "name": "Politique",
      "iab_categories": \[
        "IAB11-4"
      \]
    },
    {
      "id": "1jy",
      "name": "Jeux d’argent",
      "iab_categories": \[
        "IAB9-7"
      \]
    },
    {
      "id": "1jz",
      "name": "Rencontres",
      "iab_categories": \[
        "IAB14-1"
      \]
    },
    {
      "id": "1k0",
      "name": "Organisation à but non lucratif",
      "iab_categories": \[
        "IAB11-1",
        "IAB11-2",
        "IAB11-3",
        "IAB11-5"
      \]
    }
  \]
}

À présent, pour définir le paramètre categories sur « Science & Education », l’ensemble des iab_categories, c’est-à-dire "IAB5", "IAB15", doit être spécifié pour le line item, comme suit :

POST https://ads-api.x.com/8/accounts/55w3kv/line_items?campaign_id=f2rp3&bid_amount_local_micro=5500000&name=curated-category-line-item&product_type=MEDIA&placements=ALL_ON_TWITTER&objective=PREROLL_VIEWS&categories=IAB3,IAB13,IAB21

{
  "request": {
    "params": {
      "name": "curated-category-line-item",
      "placements": \[
        "ALL\_ON\_TWITTER"
      \],
      "bid\_amount\_local_micro": 5500000,
      "product_type": "MEDIA",
      "objective": "PREROLL_VIEWS",
      "account_id": "55w3kv",
      "categories": \[
        "IAB3",
        "IAB13",
        "IAB21"
      \],
      "campaign_id": "f2rp3"
    }
  },
  "data": {
    "bid_type": "MAX",
    "advertiser\_user\_id": 312226591,
    "name": "curated-category-line-item",
    "placements": \[
      "ALL\_ON\_TWITTER"
    \],
    "start_time": null,
    "bid\_amount\_local_micro": 5500000,
    "automatically\_select\_bid": false,
    "advertiser_domain": null,
    "target\_cpa\_local_micro": null,
    "raw_categories": \[
      "x",
      "5l",
      "9z"
    \],
    "primary\_web\_event_tag": null,
    "charge\_by": "VIEW\_3S_100PCT",
    "product\_type": "PROMOTED\_TWEETS",
    "end_time": null,
    "duration\_in\_days": null,
    "bid\_unit": "VIEW\_3S_100PCT",
    "total\_budget\_amount\_local\_micro": null,
    "objective": "PREROLL_VIEWS",
    "id": "iqwka",
    "entity_status": "ACTIVE",
    "automatic\_tweet\_promotion": null,
    "optimization": "DEFAULT",
    "frequency_cap": null,
    "android\_app\_store_identifier": null,
    "categories": \[
      "IAB3",
      "IAB13",
      "IAB21"
    \],
    "currency": "USD",
    "created_at": "2021-02-09T00:00:46Z",
    "tracking_tags": \[\],
    "ios\_app\_store_identifier": null,
    "amplify_config": {
      "auto_promote": true,
      "is_open": true
    },
    "updated_at": "2021-02-09T00:00:46Z",
    "campaign_id": "f2rp3",
    "creative_source": "MANUAL",
    "deleted": false
  }
}

​

Sélection des éditeurs

Un annonceur peut choisir de cibler une catégorie de contenu ou une catégorie organisée, avec des détails supplémentaires ci-dessous.

Remarque : Les lignes (line items) peuvent cibler des catégories organisées ou des catégories de contenu, mais pas les deux. 

​

Catégories sélectionnées

Les Catégories sélectionnées permettent aux annonceurs de cibler un groupe prédéfini d’éditeurs et peuvent être récupérées via l’endpoint GET curated_categories. Ces catégories sont spécifiques à un pays et nécessitent donc que l’élément de ligne cible le pays approprié en fonction du country_code de la catégorie.

Pour utiliser l’une de ces catégories, suivez les étapes ci-dessous dans l’ordre indiqué :

1. L’élément de ligne doit cibler le pays approprié en fonction du country_code de la Catégorie sélectionnée
2. L’endpoint POST line_item_curated_categories doit être utilisé pour associer l’élément de ligne à un curated_category_id spécifique.

Remarque : Associer un élément de ligne à une catégorie sélectionnée limite également à 5 le nombre d’éditeurs pouvant être placés sur liste de refus. La liste complète des user_id utilisés pour refuser des éditeurs spécifiques peut être récupérée depuis l’endpoint GET publishers. En outre, un élément de ligne donné ne peut cibler qu’une seule Catégorie sélectionnée à la fois.

L’exemple suivant illustre comment associer un id de catégorie sélectionnée : b0xt, disponible uniquement aux États-Unis, avec l’élément de ligne créé à l’étape précédente.

Tout d’abord, le critère de ciblage de l’élément de ligne est défini sur la valeur 96683cc9126741d

GET https://ads-api.x.com/8/targeting\_criteria/locations?country\_code=US&location_type=COUNTRIES

{
  "data": \[
    {
      "name": "États-Unis",
      "country_code": "US",
      "location_type": "COUNTRIES",
      "targeting_value": "96683cc9126741d1",
      "targeting_type": "LOCATION"
    }
  \],
  "request": {
    "params": {
      "location_type": "COUNTRIES",
      "country_code": "US"
    }
  },
  "next_cursor": null
}

POST https://ads-api.x.com/8/batch/accounts/55w3kv/targeting_criteria
\[
  {
    "operation_type": "Create",
    "params": {
      "line\_item\_id": "iqwka",
      "targeting_type": "LOCATION",
      "targeting_value": "96683cc9126741d1",
      "operator_type": "EQ"
    }
  }
\]

{
  "data": \[
    {
      "line\_item\_id": "iqwka",
      "name": "États-Unis",
      "raw_negated": false,
      "raw\_targeting\_value": "2",
      "id": "rv9hmc",
      "raw\_targeting\_type": "GEO",
      "raw\_operator\_type": "EQUAL_TO",
      "location_type": "COUNTRIES",
      "operator_type": "EQ",
      "created_at": "2021-02-09T00:06:28Z",
      "targeting_value": "96683cc9126741d1",
      "updated_at": "2021-02-09T00:06:28Z",
      "deleted": false,
      "targeting_type": "LOCATION"
    }
  \],
  "request": \[
    {
      "params": {
        "line\_item\_id": "iqwka",
        "account_id": "55w3kv",
        "operator_type": "EQ",
        "targeting_value": "96683cc9126741d1",
        "targeting_type": "LOCATION"
      },
      "operation_type": "Create"
    }
  \]
}

POST https://ads-api.x.com/8/accounts/55w3kv/line\_item\_curated\_categories?line\_item\_id=iqwka&curated\_category_id=9ddrgesiap6o

{
  "request": {
    "params": {
      "curated\_category\_id": "9ddrgesiap6o",
      "line\_item\_id": "iqwka",
      "account_id": "55w3kv"
    }
  },
  "data": {
    "line\_item\_id": "iqwka",
    "curated\_category\_id": "9ddrgesiap6o",
    "id": "xq",
    "created_at": "2021-03-30T17:26:42Z",
    "updated_at": "2021-03-30T17:26:42Z",
    "deleted": false
  }
}

​

Catégories de contenu

Les catégories de contenu, également appelées Catégories standard, peuvent être obtenues via l’endpoint GET curated_categories. Ces catégories peuvent ensuite être ciblées par l’élément de campagne au moyen des endpoints de critères de ciblage par lot. L’exemple suivant montre comment sélectionner une catégorie de contenu particulière, id : sr, qui correspond à « News & Current Events », et l’appliquer à l’élément de campagne.

Remarque : L’ensemble des iab_categories dans la réponse GET curated_categories doit être ciblé via l’endpoint de critères de ciblage. À défaut, une erreur de validation surviendra. 

GET https://ads-api.x.com/8/content_categories
{
      "name": "Actualités et événements du moment",
      "id": "sr",
      "iab_categories": \[
        "IAB12",
        "IAB14"
      \],
      "publishers\_in\_last\_thirty\_days": 124,
      "videos\_monetized\_in\_last\_thirty_days": 5429
    }
}

POST https://ads-api.x.com/8/batch/accounts/55w3kv/targeting_criteria
\[
  {
    "operation_type": "Create",
    "params": {
      "line\_item\_id": "iqwls",
      "targeting\_type": "IAB\_CATEGORY",
      "targeting_value": "IAB12",
      "operator_type": "EQ"
    }
  },
  {
    "operation_type": "Create",
    "params": {
      "line\_item\_id": "iqwls",
      "targeting\_type": "IAB\_CATEGORY",
      "targeting_value": "IAB14",
      "operator_type": "EQ"
    }
  }
\]

{
  "data": \[
    {
      "line\_item\_id": "iqwls",
      "name": "Actualités",
      "raw_negated": false,
      "raw\_targeting\_value": "5h",
      "id": "saib9p",
      "raw\_targeting\_type": "IAB_CATEGORY",
      "raw\_operator\_type": "EQUAL_TO",
      "operator_type": "EQ",
      "created_at": "2021-03-30T17:35:50Z",
      "targeting_value": "IAB12",
      "updated_at": "2021-03-30T17:35:50Z",
      "deleted": false,
      "targeting\_type": "IAB\_CATEGORY"
    },
    {
      "line\_item\_id": "iqwls",
      "name": "Société"
      "raw_negated": false,
      "raw\_targeting\_value": "5y",
      "id": "saib9q",
      "raw\_targeting\_type": "IAB_CATEGORY",
      "raw\_operator\_type": "EQUAL_TO",
      "operator_type": "EQ",
      "created_at": "2021-03-30T17:35:50Z",
      "targeting_value": "IAB14",
      "updated_at": "2021-03-30T17:35:50Z",
      "deleted": false,
      "targeting\_type": "IAB\_CATEGORY"
    }
  \],
  "request": \[
    {
      "params": {
        "line\_item\_id": "iqwls",
        "account_id": "55w3kv",
        "operator_type": "EQ",
        "targeting_value": "IAB12",
        "targeting\_type": "IAB\_CATEGORY"
      },
      "operation_type": "Create"
    },
    {
      "params": {
        "line\_item\_id": "iqwls",
        "account_id": "55w3kv",
        "operator_type": "EQ",
        "targeting_value": "IAB14",
        "targeting\_type": "IAB\_CATEGORY"
      },
      "operation_type": "Create"
    }
  \]
}

Associer le média du compte (vidéo) à l’élément de ligne

Utilisez l’endpoint POST accounts/:account_id/media_creatives pour associer la vidéo à un groupe d’annonces.

POST https://ads-api.x.com/8/accounts/55w3kv/media_creatives
line\_item\_id=4bii5&account\_media\_id=knb

{
 "data":{
   "account\_media\_id":"74g",
   "approval_status":"ACCEPTED",
   "created_at":"2016-02-11T22:23:23Z",
   "deleted":false,
   "id":"qeq",
   "landing_url":null,
   "line\_item\_id":"4bii5",
   "serving_status":"ACTIVE",
   "updated_at":"2016-02-11T22:23:23Z"
 },
 "request":{
   "params":{
     "line\_item\_id":"4bii5",
     "account\_media\_id":"knb"
   }
 }
}

​

Définir le CTA et l’URL de destination

Il est important de noter que, contrairement à la plupart des autres campagnes sur X, l’objectif VIDEO_VIEWS_PREROLL n’utilise pas de Tweets sponsorisés ni de Cards. Dans ce cas, la création vidéo est associée à votre groupe d’annonces (line item) et les informations du CTA sont associées à l’entité preroll_call_to_action. L’endpoint POST accounts/:account_id/preroll_call_to_action vous permet de configurer le bouton d’appel à l’action (CTA) et l’URL de destination.

POST https://ads-api.x.com/8/accounts/55w3kv/preroll\_call\_to_action
line\_item\_id=4bii5&call\_to\_action=VISIT\_SITE&call\_to\_action\_url=https%3A%2F%2Fx.com%2FAdsAPI

{
 "data":{
   "id":"aaa111",
   "line\_item\_id":"4bii5",
   "call\_to\_action":"REGARDER_MAINTENANT",
   "call\_to\_action_url":"https://x.com/AdsAPI",
   "created_at":"2016-02-11T22:23:23Z",
   "updated_at":"2016-02-11T22:23:23Z",
   "deleted":false
 },
 "request":{
   "params":{
     "line\_item\_id":"4bii5",
     "call\_to\_action":"VISITER_LE_SITE"
     "call\_to\_action_url":"https://x.com/AdsAPI"
   }
 }
}

​

Définir les critères de ciblage

Le critère de ciblage utilisé pour les publicités vidéo pre-roll n’est disponible qu’au moyen de notre endpoint de critères de ciblage par lots POST batch/accounts/:account_id/targeting_criteria.

Utilisez CONTENT_PUBLISHER_USER en ciblage négatif pour empêcher l’annonce d’être associée à un ensemble d’utilisateurs. Indiquez le user_id X ou le publisher_user_id correspondant aux handles à exclure.

L’endpoint GET publishers peut être utilisé pour récupérer la liste des user_id à exclure pour les catégories de contenu. Le publisher_user_id renvoyé dans la réponse de GET curated_categories peut être utilisé pour récupérer une liste d’exclusion similaire pour les catégories organisées.

Remarque : Un maximum de 5 publisher_user_id peut être exclu pour les catégories organisées et de 50 user_id pour les catégories de contenu.

POST https://ads-api.x.com/8/batch/accounts/55w3kv/targeting_criteria
\[
  {
    "operation_type": "Create",
    "params": {
      "line\_item\_id": "iqwls",
      "targeting\_type": "CONTENT\_PUBLISHER_ID",
      "targeting_value": "1917731",
      "operator_type": "NE"
    }
  }
\]

{
  "data": \[
    {
      "line\_item\_id": "iqwka",
      "name": "realsaltlake",
      "raw_negated": true,
      "raw\_targeting\_value": "aajwo",
      "id": "sajk32",
      "raw\_targeting\_type": "CONTENT_PUBLISHER",
      "raw\_operator\_type": "EQUAL_TO",
      "operator_type": "NE",
      "created_at": "2021-03-30T18:02:32Z",
      "targeting_value": 17288520,
      "updated_at": "2021-03-30T18:02:32Z",
      "deleted": false,
      "targeting\_type": "CONTENT\_PUBLISHER_USER"
    }
  \],
  "request": \[
    {
      "params": {
        "line\_item\_id": "iqwka",
        "account_id": "55w3kv",
        "operator_type": "NE",
        "targeting_value": "17288520",
        "targeting\_type": "CONTENT\_PUBLISHER_USER"
      },
      "operation_type": "Create"
    }
  \]
}

​

Lancer la campagne

Lorsque vous êtes prêt à lancer votre campagne, il vous suffit de la réactiver à l’aide de PUT accounts/:account_id/campaigns/:id.

PUT https://ads-api.x.com/8/accounts/55w3kv/campaigns/f2rp3? entity_status=ACTIVE

{
  "request": {
    "params": {
      "campaign_id": "f2rp3",
      "account_id": "55w3kv"
    }
  },
  "data": {
    "name": "test-curated-categories-api",
    "start_time": "2021-02-10T00:00:00Z",
    "reasons\_not\_servable": \[
    \],
    "servable": false,
    "purchase\_order\_number": null,
    "effective_status": "ACTIVE",
    "daily\_budget\_amount\_local\_micro": 55000000,
    "end_time": null,
    "funding\_instrument\_id": "103hp9",
    "duration\_in\_days": null,
    "standard_delivery": true,
    "total\_budget\_amount\_local\_micro": null,
    "id": "f2rp3",
    "entity_status": "ACTIVE",
    "frequency_cap": null,
    "currency": "USD"
    "created_at": "2021-02-08T23:55:38Z",
    "updated_at": "2021-02-08T23:55:38Z",
    "deleted": false
  }
}

​

Analyses

Les analyses pour les campagnes VIDEO_VIEWS_PREROLL sont disponibles via nos endpoints de statistiques.

​

Ciblage par mots-clés dans les fils

Le ciblage par mots-clés est essentiel à nos produits Promoted Tweets et permet d’accroître la portée des campagnes. Le ciblage par mots-clés dans le fil permet aux plateformes de cibler les utilisateurs de X en fonction des mots-clés présents dans leurs Tweets récents. Par exemple, si un annonceur cible la combinaison de mots-clés non ordonnée « plan + trip » et qu’un utilisateur publie un Tweet : « Je commence à planifier mon voyage à Cabo, des suggestions ? » pendant la diffusion de la campagne, cet utilisateur pourra voir peu après le Promoted Tweet de l’annonceur.

​

Comment cela fonctionne-t-il ?

TL;DR : du point de vue de l’API, ce changement est assez simple : vous pouvez désormais cibler des mots-clés sur des Tweets sponsorisés dans le fil. Il suffit de définir targeting_type sur unordered_keywords ou phrase_keywords pour les line items.

​

Guide de démarrage rapide

• Créez un nouvel élément de ligne avec le placement configuré sur ALL_ON_TWITTER ou TWITTER_TIMELINE POST accounts/:account_id/line_items
• Créez les critères de ciblage pour cet élément de ligne nouvellement créé avec BROAD_KEYWORD, puis définissez la ou les valeurs de vos mots-clés. POST accounts/:account_id/targeting_criteria
• Vous pouvez mettre à jour les mots-clés avec PUT accounts/:account_id/targeting_criteria
• Une fois votre campagne lancée, récupérez les statistiques de votre élément de ligne pour évaluer les performances. GET stats/accounts/:account_id

​

Référence de l’API

​

Comptes

Exécuter dans Postman

​

GET accounts

Récupère les détails de certains ou de tous les comptes habilités à la publicité auxquels l’utilisateur authentifié a accès.

Resource URL

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

Parameters

Name	Description
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. Type: string Example: 18ce54d4x5t
count optional	Spécifie le nombre d’enregistrements à tenter de récupérer par requête distincte. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Spécifie un curseur pour obtenir la page suivante de résultats. Voir Pagination pour plus d’informations. Type: string Example: 8x7v00oow
q optional	Une query facultative pour restreindre la ressource par name. Note: Effectue une correspondance de préfixe insensible à la casse. Type: string Min, Max length: 1, 255
sort_by optional	Trie selon un attribut pris en charge, par ordre croissant ou décroissant. Voir Sorting pour plus d’informations. Type: string Example: created_at-asc
with_deleted optional	Inclure les résultats supprimés dans la requête. Type: boolean Default: false Possible values: true, false
with_total_count optional	Inclure l’attribut de réponse total_count. Note: Ce paramètre et cursor sont mutuellement exclusifs. Note: Les requêtes qui incluent total_count sont soumises à des limites de taux plus faibles, actuellement fixées à 200 par tranche de 15 minutes. Type: boolean Default: false Possible values: true, false

​

Exemple de requête

GET https://ads-api.x.com/12/accounts?account_ids=18ce54d4x5t

Exemple de réponse

       {
         "request": {
           "params": {
             "account_ids": [
               "18ce54d4x5t"
             ]
           }
         },
         "next_cursor": null,
         "data": [
           {
             "name": "API McTestface",
             "business_name": null,
             "timezone": "America/Los_Angeles",
             "timezone_switch_at": "2016-07-21T07:00:00Z",
             "id": "18ce54d4x5t",
             "created_at": "2016-07-21T22:42:09Z",
             "updated_at": "2017-07-06T16:51:04Z",
             "business_id": null,
             "approval_status": "ACCEPTED",
             "deleted": false
           }
         ]
       }

​

GET accounts/:account_id

Récupérer un compte spécifique auquel l’utilisateur authentifié a accès.

URL de la ressource

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

Paramètres

Name	Description
account_id required	L’identifiant du compte exploité. Apparaît dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET 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 la requête. Type : boolean Valeur par défaut : false Valeurs possibles : true, false

Exemple de requête

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

Exemple de réponse

       {
         "request": {
           "params": {
             "account_id": "18ce54d4x5t"
           }
         },
         "data": {
           "name": "API McTestface",
           "business_name": null,
           "timezone": "America/Los_Angeles",
           "timezone_switch_at": "2016-07-21T07:00:00Z",
           "id": "18ce54d4x5t",
           "created_at": "2016-07-21T22:42:09Z",
           "updated_at": "2017-07-06T16:51:04Z",
           "industry_type": "TRAVEL",
           "business_id": null,
           "approval_status": "ACCEPTED"
           "deleted": false
         }
       }

​

POST accounts

Remarque : SANDBOX UNIQUEMENT

Crée un compte publicitaire dans l’environnement de sandbox.

URL de ressource

https://ads-api-sandbox.x.com/12/accounts

Paramètres

Aucun

Exemple de requête

POST https://ads-api-sandbox.x.com/12/accounts

Exemple de réponse

       {
         "request": {
           "params": {}
         },
         "next_cursor": null,
         "data": [
           {
             "name": "Compte bac à sable",
             "business_name": null,
             "timezone": "America/Los_Angeles",
             "timezone_switch_at": null,
             "id": "gq12fh",
             "created_at": "2016-07-18T23:02:20Z",
             "updated_at": "2016-07-18T23:02:20Z",
             "business_id": null,
             "approval_status": "ACCEPTED"
             "deleted": false
           }
         ]
       }

​

PUT accounts/:account_id

Met à jour le nom du compte et/ou le secteur d’activité.

URL de la ressource

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

Paramètres

Name	Description
account_id required	L’identifiant du compte exploité. Apparaît dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
name optional	Le nom du compte. Type : string Exemple : API McTestface
industry_type optional	Secteur d’activité associé au compte. Type : string Valeurs possibles : AGENCY, BUSINESS_TO_BUSINESS, ONLINE_SERVICES, EDUCATION, FINANCIAL, HEALTH, GOVERNMENT, MEDIA, MOBILE, RESTAURANT, RETAIL, TECHNOLOGY, TRAVEL, OTHER

Exemple de requête

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t?name='API McTestface 2'&industry_type=TECHNOLOGY

Exemple de réponse

       {
         "request": {
           "params": {
             "account_id": "18ce54d4x5t"
             "name": "API McTestface 2",
             "industry_type": "TECHNOLOGY"
           }
         },
         "data": {
           "name": "API McTestface 2",
           "business_name": null,
           "timezone": "America/Los_Angeles",
           "timezone_switch_at": "2016-07-21T07:00:00Z",
           "id": "18ce54d4x5t",
           "created_at": "2016-07-21T22:42:09Z",
           "updated_at": "2017-07-06T16:51:04Z",
           "industry_type": "TECHNOLOGY",
           "business_id": null,
           "approval_status": "ACCEPTED",
           "deleted": false
         }
       }

​

DELETE accounts/:account_id

Remarque : SANDBOX UNIQUEMENT

Supprime un compte publicitaire dans l’environnement sandbox.

URL de la ressource

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

Paramètres

Nom	Description
account_id requis	L’identifiant du compte exploité. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t

Exemple de requête

DELETE https://ads-api-sandbox.x.com/12/accounts/gq12fh

Exemple de réponse

       {
         "data": {
           "name": "Compte sandbox",
           "timezone": "America/Los_Angeles",
           "timezone_switch_at": null,
           "id": "gq12fh",
           "created_at": "2016-07-18T23:02:20Z",
           "updated_at": "2017-08-23T18:21:10Z",
           "approval_status": "ACCEPTÉ",
           "deleted": true
         },
         "request": {
           "params": {
             "account_id": "gq12fh"
           }
         }
       }

​

Apps de comptes

Exécuter dans Postman ❯

​

GET account_apps

Récupère les détails de toutes les applications mobiles associées au compte publicitaire spécifié.

URL de la ressource

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

Paramètres

Name	Description
account_id required	L’identifiant du compte exploité. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Exemple: 18ce54d4x5t
count optional	Spécifie le nombre d’enregistrements à essayer 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 suivante de résultats. Voir Pagination pour plus d’informations. Type: string Exemple: 8x7v00oow
sort_by optional	Trie selon un attribut pris en charge, par ordre croissant ou décroissant. Voir Sorting pour plus d’informations. Type: string Exemple: created_at-asc
with_deleted optional	Inclut les résultats supprimés dans la 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. Remarque: Ce paramètre et cursor sont mutuellement exclusifs. Remarque: Les requêtes incluant total_count sont soumises à des limites de taux plus faibles, actuellement fixées à 200 par 15 minutes. Type: boolean Valeur par défaut: false Valeurs possibles: true, false

Exemple de requête

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_apps

Exemple de réponse

       {
         "request": {
           "params": {
             "account_ids": [
               "18ce54d4x5t"
             ]
           }
         },
         "next_cursor": null,
         "data": [
          {
            "app_store_identifier": "com.twitter.android",
            "conversion_tracking_enabled": false,
            "deep_link_pattern": "twitter://",
            "id": "4x",
            "created_at": "2019-06-20T22:36:16Z",
            "updated_at": "2021-10-19T20:05:29Z",
            "os_type": "Android",
            "deleted": false
          }
         ]
       }

​

Historique du compte

Exécuter dans Postman

​

GET accounts/:account_id/account_history

Récupère un récapitulatif des modifications apportées à l’entity_id spécifié dans la requête.

Remarque : Cet endpoint est actuellement en bêta et nécessite un autorisationnement (allowlisting).

Resource URL

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

Parameters

Name	Description
account_id required	L’identifiant du compte exploité. Type: string Example: 18ce54d4x5t
count optional	Spécifie le nombre d’enregistrements à tenter de récupérer par requête. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Spécifie un curseur pour obtenir la page suivante de résultats. Voir Pagination pour plus d’informations. Type: string Example: 8x7v00oow
entity_type required	Le type d’entité pour lequel récupérer les données. Type: enum Example: PROMOTED_TWEET Possible values: CAMPAIGN, LINE_ITEM, PROMOTED_TWEET, TARGETING_CRITERIA, PROMOTED_ACCOUNT
entity_id required	L’entité spécifique pour laquelle récupérer les données. Type: string Example: 8u94t
start_time required	Restreint les données récupérées à l’heure de début spécifiée, exprimée en ISO 8601. Remarque : Doit être exprimée en heures pleines (0 minute et 0 seconde). Type: string Example: 2017-05-19T07:00:00Z
end_time required	Restreint les données récupérées à l’heure de fin spécifiée, exprimée en ISO 8601. Remarque : Doit être exprimée en heures pleines (0 minute et 0 seconde). Type: string Example: 2017-05-26T07:00:00Z
user_id optional	Restreint la réponse à un utilisateur spécifique. Type: long Example: 3271358660

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_history?entity_type=CAMPAIGN&entity_id=fc3h5&count=1

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "entity": "CAMPAIGN",
          "entity_id": "fc3h5",
          "count": 1
        }
      },
      "next_cursor": "1r2407sb4lc",
      "data": [
        {
          "change_by": {
            "user_id": "982978172",
            "platform": "API_OTHER"
          },
          "changes": {},
          "change_time": "2021-04-02T20:55:42Z",
          "entity_id": "fc3h5",
          "entity": "CAMPAIGN",
          "entity_data": {
            "name": "campagne_test",
            "start_time": "2021-04-02T18:59:11Z",
            "purchase_order_number": null,
            "daily_budget_amount_local_micro": 100000000,
            "end_time": null,
            "duration_in_days": null,
            "standard_delivery": true,
            "total_budget_amount_local_micro": 100000000,
            "entity_status": "ACTIVE",
            "frequency_cap": null,
            "created_at": "2021-04-02T20:55:42Z",
            "updated_at": "2021-04-02T20:55:42Z",
            "deleted": false
          },
          "change_type": "CREATE"
        }
      ]
    }

​

Catégories d’activité des annonceurs

Exécuter dans Postman

​

GET advertiser_business_categories

Demandez les categories d’activité publicitaire valides pour les groupes d’annonces (line_items) afin de décrire la marque d’un annonceur aux éditeurs.

Remarque : ces catégories s’appliquent uniquement aux line_items avec l’objectif PREROLL_VIEWS et sont distinctes des content_categories utilisées pour les critères de ciblage.

Chaque advertiser_business_categories représente un ensemble de catégories IAB. Lors de la création d’un groupe d’annonces avec l’objectif PREROLL_VIEWS, une ou deux advertiser_business_categories doivent être définies pour le groupe d’annonces. Cela peut être fait en indiquant la valeur du paramètre de requête categories sur l’endpoint line item avec l’ensemble des iab_categories correspondantes disponibles via cet endpoint.

Des informations supplémentaires sont disponibles dans le guide de l’objectif Video Views Preroll

Resource URL

https://ads-api.x.com/12/advertiser_business_categories

Parameters

Aucun paramètre de requête

Example Request

GET https://ads-api.x.com/12/advertiser_business_categories

Example Response

{
      "request": {
        "params": {}
      },
      "next_cursor": null,
      "data": [
        {
          "id": "1jl",
          "name": "Produits de grande consommation",
          "iab_categories": [
            "IAB9-26",
            "IAB9-18",
            "IAB9-29",
            "IAB9-1",
            "IAB9-8",
            "IAB9-22",
            "IAB6",
            "IAB9-5",
            "IAB9-12",
            "IAB9-11",
            "IAB9-23",
            "IAB9-14",
            "IAB4",
            "IAB9-25",
            "IAB9-17",
            "IAB23",
            "IAB9-24",
            "IAB9-13",
            "IAB16",
            "IAB9-4",
            "IAB9-9",
            "IAB9-20",
            "IAB22",
            "IAB9-28",
            "IAB9-27",
            "IAB9-16",
            "IAB9-31",
            "IAB9-3",
            "IAB9-19",
            "IAB10",
            "IAB9-2",
            "IAB9-6",
            "IAB9-21",
            "IAB9-10",
            "IAB9-15"
          ]
        },
        {
          "id": "1jm",
          "name": "Santé et pharmacie",
          "iab_categories": [
            "IAB7"
          ]
        },
        {
          "id": "1jn",
          "name": "Alcool",
          "iab_categories": [
            "IAB8-5",
            "IAB8-18"
          ]
        },
        {
          "id": "1jo",
          "name": "Restauration",
          "iab_categories": [
            "IAB8-10",
            "IAB8-8",
            "IAB8-7",
            "IAB8-15",
            "IAB8-3",
            "IAB8-4",
            "IAB8-1",
            "IAB8-16",
            "IAB8-12",
            "IAB8-13",
            "IAB8-17",
            "IAB8-11",
            "IAB8-6",
            "IAB8-9",
            "IAB8-2",
            "IAB8-14"
          ]
        },
        {
          "id": "1jp",
          "name": "Services financiers",
          "iab_categories": [
            "IAB3",
            "IAB13",
            "IAB21"
          ]
        },
        {
          "id": "1jq",
          "name": "Commerce de détail",
          "iab_categories": [
            "IAB18"
          ]
        },
        {
          "id": "1jr",
          "name": "Voyage",
          "iab_categories": [
            "IAB20"
          ]
        },
        {
          "id": "1js",
          "name": "Jeux vidéo",
          "iab_categories": [
            "IAB9-30"
          ]
        },
        {
          "id": "1jt",
          "name": "Technologie",
          "iab_categories": [
            "IAB19-22",
            "IAB19-13",
            "IAB19-4",
            "IAB19-33",
            "IAB19-26",
            "IAB19-3",
            "IAB19-16",
            "IAB19-9",
            "IAB19-32",
            "IAB19-25",
            "IAB19-30",
            "IAB19-36",
            "IAB19-21",
            "IAB5",
            "IAB19-12",
            "IAB19-28",
            "IAB19-17",
            "IAB19-8",
            "IAB19-7",
            "IAB19-24",
            "IAB15",
            "IAB19-11",
            "IAB19-31",
            "IAB19-20",
            "IAB19-15",
            "IAB19-1",
            "IAB19-35",
            "IAB19-29",
            "IAB19-34",
            "IAB19-23",
            "IAB19-2",
            "IAB19-5",
            "IAB19-14",
            "IAB19-27",
            "IAB19-10",
            "IAB19-19"
          ]
        },
        {
          "id": "1ju",
          "name": "Télécommunications",
          "iab_categories": [
            "IAB19-6",
            "IAB19-18"
          ]
        },
        {
          "id": "1jv",
          "name": "Automobile",
          "iab_categories": [
            "IAB2"
          ]
        },
        {
          "id": "1jw",
          "name": "Médias et divertissement",
          "iab_categories": [
            "IAB14-8",
            "IAB14-4",
            "IAB1-5",
            "IAB14-7",
            "IAB1-7",
            "IAB17",
            "IAB14-3",
            "IAB1-1",
            "IAB12",
            "IAB1-6",
            "IAB25-1",
            "IAB1-2",
            "IAB14-2",
            "IAB14-6",
            "IAB1-3",
            "IAB1-4",
            "IAB14-5"
          ]
        },
        {
          "id": "1jx",
          "name": "Politique",
          "iab_categories": [
            "IAB11-4"
          ]
        },
        {
          "id": "1jy",
          "name": "Jeux d’argent",
          "iab_categories": [
            "IAB9-7"
          ]
        },
        {
          "id": "1jz",
          "name": "Rencontres",
          "iab_categories": [
            "IAB14-1"
          ]
        },
        {
          "id": "1k0",
          "name": "Organisation à but non lucratif"
          "iab_categories": [
            "IAB11-1",
            "IAB11-2",
            "IAB11-3",
            "IAB11-5"
          ]
        }
      ]
    }

​

Estimation de l’audience

Exécuter dans Postman

POST accounts/:account_id/audience_estimate

​

Déterminez la taille approximative de l’audience de vos campagnes.

Cet endpoint accepte un tableau d’objets JSON contenant les paramètres des objets de critères de ciblage. Une liste des paramètres de critères de ciblage requis et optionnels est disponible sur l’endpoint POST accounts/:account_id/targeting_criteria. Les requêtes doivent être des HTTP POST avec un corps JSON et un en-tête Content-Type: application/json.

Remarque : Vous devez spécifier au moins un critère de ciblage primaire ; vous pouvez consulter la liste de tous les critères de ciblage primaires sur notre page de ciblage des campagnes.

Resource URL

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

Parameters

Name	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Exemple : 18ce54d4x5t
targeting_criteria required	Un objet JSON contenant tous les paramètres des objets de critères de ciblage. Une liste des paramètres de critères de ciblage requis et optionnels est disponible sur l’endpoint POST accounts/:account_id/targeting_criteria.
operator_type optional	Spécifie la relation que le critère de ciblage doit avoir. Par exemple, pour définir un ciblage négatif, utilisez operator_type=NE. Type : enum Valeurs possibles : EQ, NE Par défaut : EQ

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/audience_estimate

    {
        "targeting_criteria": [
            {
                "targeting_type": "BROAD_KEYWORD",
                "targeting_value": "NBA",
                "operator_type": "EQ"
            },
            {
                "targeting_type": "BROAD_KEYWORD",
                "targeting_value": "tech",
                "operator_type": "NE"
            },
            {
                "targeting_type": "LOCATION",
                "targeting_value": "96683cc9126741d1",
                "operator_type": "EQ"
            },
            {
                "targeting_type": "SIMILAR_TO_FOLLOWERS_OF_USER",
                "targeting_value": "14230524"
            },
            {
                "targeting_type": "SIMILAR_TO_FOLLOWERS_OF_USER",
                "targeting_value": "90420314"
            }
        ]
    }

Exemple de réponse

    {
      "request": {
        "params": {
          "targeting_criteria": null,
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "audience_size": {
          "min": 38236294,
          "max": 42261167
        }
      }
    }

​

Accès utilisateur authentifié

Exécuter dans Postman

​

GET accounts/:account_id/authenticated_user_access

Récupère les autorisations de l’utilisateur actuellement authentifié (access_token) relatives au compte publicitaire spécifié. Ces autorisations correspondent à celles affichées sur ads.x.com.

Valeurs possibles :

• ACCOUNT_ADMIN : Accès complet pour modifier les campagnes et consulter les statistiques, y compris la possibilité d’ajouter ou de supprimer des utilisateurs et de modifier les paramètres
• AD_MANAGER : Accès complet pour modifier les campagnes et consulter les statistiques, mais sans possibilité d’ajouter ou de supprimer des utilisateurs ni de modifier les paramètres
• CREATIVE_MANAGER : Accès pour modifier les créations et afficher les aperçus, mais aucun accès pour créer ou modifier des campagnes
• CAMPAIGN_ANALYST : Accès pour afficher les campagnes et consulter les statistiques, mais aucun accès pour créer ou modifier des campagnes
• ANALYST (« Organic Analyst » sur ads.x.com) : Accès pour consulter les analyses organiques et les insights d’audience, mais aucun accès pour créer, modifier ou afficher des campagnes
• PARTNER_AUDIENCE_MANAGER : Accès via l’API uniquement pour consulter et modifier les audiences des partenaires de données, mais aucun accès aux campagnes, créations ou autres types d’audience.

De plus, l’autorisation TWEET_COMPOSER indique que l’utilisateur authentifié peut créer des Tweets non diffusés (ou « Promoted-only ») au nom de l’annonceur. Ceci n’est disponible que pour les utilisateurs disposant d’un accès ACCOUNT_ADMIN, AD_MANAGER ou CREATIVE_MANAGER.

Resource URL

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

Parameters

Aucun

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/authenticated_user_access

Example Response

    {
      "data": {
        "user_id": "2417045708",
        "permissions": [
          "ACCOUNT_ADMIN",
          "TWEET_COMPOSER"
        ]
      },
      "request": {
        "params": {
          "account_id": "18ce54d4x5t"
        }
      }
    }

​

Règles d’enchère

Exécuter dans Postman

​

GET bidding_rules

Récupère les règles d’enchères pour une ou plusieurs devises. La réponse indiquera les enchères CPE (coût par engagement) minimales et maximales.

Même si ces règles d’enchères évoluent rarement, il est recommandé que vos systèmes actualisent ces endpoints au moins une fois par mois.

Resource URL

https://ads-api.x.com/12/bidding_rules

Parameters

Name	Description
currency optional	Type de devise utilisé pour filtrer les résultats, identifié via la norme ISO‑4217. Il s’agit d’une chaîne de trois lettres, par exemple « USD » ou « EUR ». Omettez ce paramètre pour récupérer toutes les règles d’enchères. Type: string Example: USD

Example Request

GET https://ads-api.x.com/12/bidding_rules?currency=USD

Example Response

    {
      "request": {
        "params": {
          "currency": "USD"
        }
      },
      "data_type": "bidding_rule",
      "data": [
        {
          "currency": "USD",
          "minimum_cpe_bid_local_micro": 10000,
          "maximum_cpe_bid_local_micro": 1000000000,
          "minimum_denomination": 10000
        }
      ],
      "total_count": 1
    }

​

Campagnes

Exécuter dans Postman

​

GET accounts/:account_id/campaigns

Récupérer les détails d’une partie ou de l’ensemble des campagnes associées au compte en cours.

Resource URL

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

Parameters

Name	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: 18ce54d4x5t
campaign_ids optional	Limite la réponse aux campagnes souhaitées en fournissant une liste d’identifiants séparés par des virgules. Jusqu’à 200 IDs peuvent être fournis. Type: string Example: 8wku2
count optional	Spécifie le nombre d’enregistrements à tenter de récupérer par requête distincte. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Spécifie un curseur pour obtenir la page suivante de résultats. Voir Pagination pour plus d’informations. Type: string Example: 8x7v00oow
funding_instrument_ids optional	Limite la réponse aux campagnes relevant d’instruments de financement spécifiques en fournissant une liste d’identifiants séparés par des virgules. Jusqu’à 200 IDs peuvent être fournis. Type: string Example: lygyi
q optional	Une query facultative pour filtrer la ressource par name. Type: string Min, Max length: 1, 255
sort_by optional	Trie selon un attribut pris en charge, par ordre croissant ou décroissant. Voir Sorting pour plus d’informations. Type: string Example: created_at-asc
with_deleted optional	Inclure les résultats supprimés dans votre requête. Type: boolean Default: false Possible values: true, false
with_draft optional	Inclure les campagnes à l’état de brouillon dans votre requête. Type: boolean Default: false Possible values: true, false
with_total_count optional	Inclure l’attribut de réponse total_count. Note : Ce paramètre et cursor sont mutuellement exclusifs. Note : Les requêtes qui incluent total_count sont soumises à des limites de taux plus strictes, actuellement fixées à 200 par période de 15 minutes. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns?campaign_ids=8wku2

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "campaign_ids": [
            "8wku2"
          ]
        }
      },
      "next_cursor": null,
      "data": [
        {
          "name": "test",
          "budget_optimization": "CAMPAIGN",
          "reasons_not_servable": [
            "PAUSED_BY_ADVERTISER",
            "INCOMPLETE"
          ],
          "servable": false,
          "purchase_order_number": null,
          "effective_status": "UNKNOWN",
          "daily_budget_amount_local_micro": 10000000,
          "funding_instrument_id": "lygyi",
          "duration_in_days": null,
          "standard_delivery": false,
          "total_budget_amount_local_micro": null,
          "id": "8wku2",
          "entity_status": "PAUSED",
          "frequency_cap": null,
          "currency": "USD",
          "created_at": "2022-06-03T21:38:07Z",
          "updated_at": "2022-06-03T21:38:07Z",
          "deleted": false
        }
      ]
    }

​

GET accounts/:account_id/campaigns/:campaign_id

Récupère une campagne spécifique associée au compte actuel.

URL de la ressource

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

Paramètres

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

Exemple de requête

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns/8wku2

Exemple de réponse

    {
      "request": {
        "params": {
          "campaign_id": "8wku2",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "name": "test",
        "budget_optimization": "CAMPAIGN",
          "PAUSED_BY_ADVERTISER",
          "PAUSED_BY_ADVERTISER",
          "INCOMPLETE"
        ],
        "servable": false,
        "purchase_order_number": null,
        "effective_status": "UNKNOWN",
        "daily_budget_amount_local_micro": 10000000,
        "funding_instrument_id": "lygyi",
        "duration_in_days": null,
        "standard_delivery": false,
        "total_budget_amount_local_micro": null,
        "id": "8wku2",
        "entity_status": "PAUSED",
        "frequency_cap": null,
        "currency": "USD",
        "created_at": "2022-06-03T21:38:07Z",
        "updated_at": "2022-06-03T21:38:07Z",
        "deleted": false
      }
    }

​

POST accounts/:account_id/campaigns

Créer une nouvelle campagne associée au compte en cours.

Remarque : Il existe une limite par défaut de 200 campagnes actives par compte. Cependant, il n’y a aucune limite quant au nombre de campagnes inactives. Cette limite peut être portée à 8 000 campagnes actives. Pour activer la limite supérieure, l’annonceur doit en faire la demande à son X Account Manager.

URL de la ressource

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

Paramètres

Nom	Description
account_id obligatoire	L’identifiant du compte exploité. Il apparaît dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte indiqué doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
funding_instrument_id obligatoire	L’identifiant de l’instrument de financement sous lequel créer la campagne. Type : string Exemple : lygyi
name obligatoire	Le nom de la campagne. Longueur maximale : 255 caractères. Type : string Exemple : demo
budget_optimization optionnel	Sélectionnez le type d’optimisation budgétaire à appliquer. Type : enum Par défaut : CAMPAIGN Valeurs possibles : CAMPAIGN, LINE_ITEM
daily_budget_amount_local_micro parfois obligatoire	Le montant du budget quotidien à allouer à la campagne. La devise associée à l’instrument de financement spécifié sera utilisée. Pour l’USD, 5,50 $ est représenté par 5500000. Remarque : Ce montant doit être inférieur ou égal à total_budget_amount_local_micro et est requis pour la plupart des types d’instruments de financement. Type : long Exemple : 5500000
entity_status optionnel	Le statut de la campagne. Type : enum Par défaut : ACTIVE Valeurs possibles : ACTIVE, DRAFT, PAUSED
purchase_order_number optionnel	Le numéro de bon de commande. Utilisez ce champ pour faciliter le rapprochement des factures. Longueur maximale : 50 caractères. Type : string Exemple : D00805843
standard_delivery optionnel	Activez la diffusion standard ou accélérée. Voir Budget Pacing pour plus d’informations sur la diffusion standard ou accélérée. Disponible uniquement lorsque budget_optimization est défini sur CAMPAIGN. Type : boolean Par défaut : true Valeurs possibles : true, false
total_budget_amount_local_micro optionnel	Le montant total du budget à allouer à la campagne. La devise associée à l’instrument de financement spécifié sera utilisée. Pour l’USD, 37,50 $ est représenté par 37500000. Type : long Exemple : 37500000

Exemple de requête

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns?funding_instrument_id=lygyi&name=demo&daily_budget_amount_local_micro=140000000&entity_status=PAUSED&budget_optimization=CAMPIAGN&standard_delivery=false

Exemple de réponse

    {
      "request": {
        "params": {
          "name": "demo",
          "budget_optimization": "CAMPAIGN",
          "daily_budget_amount_local_micro": 140000000,
          "funding_instrument_id": "lygyi",
          "standard_delivery": false,
          "entity_status": "PAUSED",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "name": "demo",
        "budget_optimization": "CAMPAIGN",
        "reasons_not_servable": [
          "PAUSED_BY_ADVERTISER",
          "INCOMPLETE"
        ],
        "servable": false,
        "purchase_order_number": null,
        "effective_status": "UNKNOWN",
        "daily_budget_amount_local_micro": 140000000,
        "funding_instrument_id": "lygyi",
        "duration_in_days": null,
        "standard_delivery": false,
        "total_budget_amount_local_micro": null,
        "id": "hwtbm",
        "entity_status": "PAUSED",
        "frequency_cap": null,
        "currency": "USD",
        "created_at": "2022-06-03T21:38:07Z",
        "updated_at": "2022-06-03T21:38:07Z",
        "deleted": false
      }
    }

​

POST batch/accounts/:account_id/campaigns

Permet de créer en lot de nouvelles campagnes en une seule requête.

Requêtes par lot

• La taille maximale actuelle d’un lot est de 40.
• 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 — conservent 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, dans leur structure, aux endpoints correspondants à un seul élément.

Erreurs par lot

• Les erreurs au niveau de la requête (p. ex. dépassement de la taille maximale du lot) apparaissent dans la réponse sous l’objet errors.
• Les erreurs au niveau de l’élément (p. ex. paramètre de campagne requis manquant) apparaissent dans la réponse sous l’objet operation_errors.

URL de la ressource

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

Paramètres

Name	Description
operation_type required	Le type d’opération appliqué à chaque élément. Type : enum Valeurs possibles : Create, Delete, Update
params required	Un objet JSON contenant tous les paramètres des objets campagne. Pour la liste des paramètres de campagne obligatoires et facultatifs, voir ici.

Exemple de requête

POST 'Content-Type: application/json' https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/campaigns

    [
      {
        "operation_type":"Create",
        "params":{
          "name":"campagnes en lot",
          "funding_instrument_id":"lygyi",
          "daily_budget_amount_local_micro":140000000,
          "entity_status":"PAUSED",
          "budget_optimization":"CAMPAIGN"
        }
      }
    ]

Exemple de réponse

    {
      "data": [
        {
          "name": "campagnes groupées",
          "budget_optimization": "CAMPAIGN",
          "reasons_not_servable": [
            "PAUSED_BY_ADVERTISER",
            "INCOMPLETE"
          ],
          "servable": false,
          "purchase_order_number": null,
          "effective_status": "INCONNU",
          "daily_budget_amount_local_micro": 140000000,
          "funding_instrument_id": "lygyi",
          "duration_in_days": null,
          "standard_delivery": false,
          "total_budget_amount_local_micro": null,
          "id": "8yn7m",
          "entity_status": "EN PAUSE",
          "frequency_cap": null,
          "currency": "USD",
          "created_at": "2022-06-03T21:38:07Z",
          "updated_at": "2022-06-03T21:38:07Z",
          "deleted": false
        }
      ],
      "request": [
        {
          "params": {
            "name": "batch campaigns",
            "funding_instrument_id": "lygyi",
            "daily_budget_amount_local_micro": 140000000,
            "entity_status": "PAUSED",
            "budget_optimization":"CAMPAIGN",
            "account_id": "18ce54d4x5t"
          },
          "operation_type": "Create"
        }
      ]
    }

​

PUT accounts/:account_id/campaigns/:campaign_id

Met à jour la campagne spécifiée associée au compte en cours.

URL de la ressource

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

Paramètres

Nom	Description
account_id obligatoire	L’identifiant du compte exploité. Figure dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Exemple: 18ce54d4x5t
campaign_id obligatoire	La référence de la campagne utilisée dans la requête. Type: string Exemple: 8wku2
budget_optimization optionnel	Sélectionne le type d’optimisation budgétaire à appliquer. Type: enum Par défaut : CAMPAIGN Valeurs possibles : CAMPAIGN, LINE_ITEM
daily_budget_amount_local_micro optionnel	Le montant du budget quotidien à allouer à la campagne. La devise associée à l’instrument de financement spécifié sera utilisée. Pour l’USD, 5,50 $ est représenté par 5500000. S’il n’est pas fourni, la campagne dépensera de manière uniforme en fonction du budget total et pendant toute la durée du vol de campagne. Remarque : doit être inférieur ou égal à total_budget_amount_local_micro. Type: long Exemple: 5500000
entity_status optionnel	Le statut de la campagne. Type: enum Valeurs possibles : ACTIVE, PAUSED
name optionnel	Le nom de la campagne. Longueur maximale : 255 caractères. Type: string Exemple: demo
purchase_order_number optionnel	Le numéro de bon de commande. Utilisez ce champ pour faciliter le rapprochement des factures. Longueur maximale : 50 caractères. Type: string Exemple: D00805843
standard_delivery optionnel	Active la diffusion standard ou accélérée. Voir Budget Pacing pour plus d’informations sur la diffusion standard versus accélérée. Disponible uniquement lorsque budget_optimization est défini sur CAMPAIGN. Type: boolean Par défaut : true Valeurs possibles : true, false
total_budget_amount_local_micro optionnel	Le montant du budget total à allouer à la campagne. La devise associée à l’instrument de financement spécifié sera utilisée. Pour l’USD, 37,50 $ est représenté par 37500000. Type: long Exemple: 140000000

Exemple de requête

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns/8wku2?total_budget_amount_local_micro=140000000

Exemple de réponse

    {
      "request": {
        "params": {
          "campaign_id": "8wku2",
          "daily_budget_amount_local_micro": 140000000,
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "name": "test",
        "budget_optimization": "CAMPAIGN",
        "reasons_not_servable": [
          "PAUSED_BY_ADVERTISER",
          "INCOMPLETE"
        ],
        "servable": false,
        "purchase_order_number": null,
        "effective_status": "UNKNOWN",
        "daily_budget_amount_local_micro": 140000000,
        "funding_instrument_id": "lygyi",
        "duration_in_days": null,
        "standard_delivery": false,
        "total_budget_amount_local_micro": null,
        "id": "8wku2",
        "entity_status": "PAUSED",
        "frequency_cap": null,
        "currency": "USD",
        "created_at": "2022-06-03T21:38:07Z",
        "updated_at": "2022-06-03T21:53:54Z",
        "deleted": false
      }
    }

​

DELETE accounts/:account_id/campaigns/:campaign_id

Supprime la campagne spécifiée appartenant au compte actuel.

Remarque : La suppression d’une campagne est irréversible et toute tentative ultérieure de supprimer la ressource renverra un code HTTP 404.

URL de la ressource

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

Paramètres

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

Exemple de requête

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns/8yn7m

Exemple de réponse

    {
      "request": {
        "params": {
          "campaign_id": "8yn7m",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "name": "test",
        "budget_optimization": "CAMPAIGN",
        "reasons_not_servable": [],
        "servable": null,
        "purchase_order_number": null,
        "effective_status": "RUNNING",
        "daily_budget_amount_local_micro": 140000000,
        "funding_instrument_id": "lygyi",
        "duration_in_days": null,
        "standard_delivery": false,
        "total_budget_amount_local_micro": null,
        "id": "8yn7m",
        "entity_status": "PAUSED",
        "frequency_cap": null,
        "currency": "USD",
        "created_at": "2022-06-03T21:38:07Z",
        "updated_at": "2022-06-03T21:56:35Z",
        "deleted": true
      }
    }

​

Catégories de contenu

Exécuter dans Postman

​

GET content_categories

Récupère les categories de contenu valides à définir comme targeting_criteria pour un poste budgétaire.

Chaque content_category est associée à une ou plusieurs IAB Categories. Pour cela, définissez targeting_type sur IAB_CATEGORY sur l’endpoint de traitement par lots targeting_critera afin d’inclure l’ensemble des iab_categories correspondantes renvoyées par la requête content_categories. À défaut, une erreur de validation sera renvoyée.

Les informations éditeur pour chacune de ces catégories de contenu peuvent être récupérées à l’aide de l’endpoint GET publishers.

Des informations supplémentaires sont disponibles dans le Video Views Pre-roll Objective Guide.

URL de la ressource

https://ads-api.x.com/12/content_categories

Paramètres

Aucun paramètre de requête

Exemple de requête

GET https://ads-api.x.com/12/content_categories

Exemple de réponse

{
      "request": {
        "params": {}
      },
      "next_cursor": null,
      "data": [
        {
          "name": "Automobile (voitures, camions, sport automobile)",
          "id": "ru",
          "iab_categories": [
            "IAB2"
          ],
          "publishers_in_last_thirty_days": 12,
          "videos_monetized_in_last_thirty_days": 316
        },
        {
          "name": "Comédie",
          "id": "sk",
          "iab_categories": [
            "IAB1-4"
          ],
          "publishers_in_last_thirty_days": 19,
          "videos_monetized_in_last_thirty_days": 174
        },
        {
          "name": "Créateurs numériques",
          "id": "sl",
          "iab_categories": [
            "IAB25-1"
          ],
          "publishers_in_last_thirty_days": 110,
          "videos_monetized_in_last_thirty_days": 1257
        },
        {
          "name": "Divertissement et culture pop",
          "id": "sm",
          "iab_categories": [
            "IAB1-1",
            "IAB1-2",
            "IAB1-3",
            "IAB1-5"
          ],
          "publishers_in_last_thirty_days": 120,
          "videos_monetized_in_last_thirty_days": 3482
        },
        {
          "name": "Actualité financière et économie",
          "id": "sn",
          "iab_categories": [
            "IAB3",
            "IAB13",
            "IAB21"
          ],
          "publishers_in_last_thirty_days": 29,
          "videos_monetized_in_last_thirty_days": 1461
        },
        {
          "name": "Alimentation et boissons",
          "id": "so",
          "iab_categories": [
            "IAB8-8",
            "IAB8-12",
            "IAB8-17",
            "IAB8-2",
            "IAB8-3",
            "IAB8-7",
            "IAB8-11",
            "IAB8-4",
            "IAB8-14",
            "IAB8-10",
            "IAB8-15",
            "IAB8-13",
            "IAB8-9",
            "IAB8-16",
            "IAB8-6",
            "IAB8-1"
          ],
          "publishers_in_last_thirty_days": 24,
          "videos_monetized_in_last_thirty_days": 516
        },
        {
          "name": "Lifestyle (mode, voyage, bien-être)",
          "id": "sp",
          "iab_categories": [
            "IAB16",
            "IAB9-21",
            "IAB9-4",
            "IAB9-25",
            "IAB9-8",
            "IAB4",
            "IAB9-3",
            "IAB9-15",
            "IAB7",
            "IAB6",
            "IAB9-11",
            "IAB9-16",
            "IAB9-7",
            "IAB9-20",
            "IAB9-24",
            "IAB9-17",
            "IAB9-12",
            "IAB9-31",
            "IAB9-27",
            "IAB10",
            "IAB9-10",
            "IAB9-23",
            "IAB9-6",
            "IAB9-18",
            "IAB9-13",
            "IAB9-1",
            "IAB9-28",
            "IAB20",
            "IAB9-5",
            "IAB9-26",
            "IAB22",
            "IAB23",
            "IAB9-9",
            "IAB9-22",
            "IAB18",
            "IAB9-2",
            "IAB9-19",
            "IAB9-14",
            "IAB9-29"
          ],
          "publishers_in_last_thirty_days": 67,
          "videos_monetized_in_last_thirty_days": 2412
        },
        {
          "name": "Musique",
          "id": "sq",
          "iab_categories": [
            "IAB1-6"
          ],
          "publishers_in_last_thirty_days": 31,
          "videos_monetized_in_last_thirty_days": 518
        },
        {
          "name": "Actualités et faits d’actualité",
          "id": "sr",
          "iab_categories": [
            "IAB12",
            "IAB14"
          ],
          "publishers_in_last_thirty_days": 125,
          "videos_monetized_in_last_thirty_days": 5507
        },
        {
          "name": "Politique",
          "id": "s4",
          "iab_categories": [
            "IAB11"
          ],
          "publishers_in_last_thirty_days": 19,
          "videos_monetized_in_last_thirty_days": 1402
        },
        {
          "name": "Sciences et éducation",
          "id": "ss",
          "iab_categories": [
            "IAB5",
            "IAB15"
          ],
          "publishers_in_last_thirty_days": 7,
          "videos_monetized_in_last_thirty_days": 132
        },
        {
          "name": "Sports",
          "id": "se",
          "iab_categories": [
            "IAB17"
          ],
          "publishers_in_last_thirty_days": 403,
          "videos_monetized_in_last_thirty_days": 18281
        },
        {
          "name": "Technologies",
          "id": "sg",
          "iab_categories": [
            "IAB19"
          ],
          "publishers_in_last_thirty_days": 13,
          "videos_monetized_in_last_thirty_days": 1089
        },
        {
          "name": "Télévision",
          "id": "sh",
          "iab_categories": [
            "IAB1-7"
          ],
          "publishers_in_last_thirty_days": 58,
          "videos_monetized_in_last_thirty_days": 1307
        },
        {
          "name": "Esport et jeux vidéo"
          "id": "s0",
          "iab_categories": [
            "IAB9-30"
          ],
          "publishers_in_last_thirty_days": 109,
          "videos_monetized_in_last_thirty_days": 1844
        }
      ],
      "total_count": 15
    }

​

Catégories sélectionnées

Exécuter dans Postman

​

GET accounts/:account_id/curated_categories

Récupère la liste des catégories sélectionnées disponibles pour les country_codes fournis

Chaque curated_category n’est disponible que dans certains pays indiqués par les country_codes dans la réponse.

Des informations supplémentaires sont disponibles dans le guide de l’objectif Pre-roll pour les vues vidéo.

URL de la ressource

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

Paramètres

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. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Exemple : 18ce54d4x5t
country_codes requis	Limite la réponse aux pays souhaités en indiquant une liste, séparée par des virgules, de codes pays ISO à deux lettres. Jusqu’à 200 identifiants peuvent être fournis. Type: string Exemple : US
cursor optionnel	Spécifie un curseur pour obtenir la page suivante de résultats. Voir Pagination pour plus d’informations. Type: string Exemple : 8x7v00oow

Exemple de requête

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/curated_categories?country_codes=US

Exemple de réponse

{
      "request": {
        "params": {
          "country_codes": [
            "US"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "name": "Basket-ball",
          "description": "Diffusez à côté du meilleur contenu quotidien de basket-ball, incluant des équipes universitaires, des équipes professionnelles et les principaux médias sportifs partageant des vidéos de basket-ball en saison et hors saison.",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "20265254",
            "378174762",
            "900368808",
            "18939563",
            "18371803",
            "18360370",
            "770658432928079872",
            "11026952",
            "37085464",
            "16212685",
            "57422635",
            "281669945",
            "7117962",
            "23065057",
            "41688179",
            "29779226",
            "900280416",
            "364460082",
            "902030382",
            "19409270",
            "19077044",
            "18139461",
            "14992591",
            "66753565",
            "667563",
            "16727749",
            "40941404",
            "18481113",
            "791598918",
            "16201775",
            "15900167",
            "45891626",
            "191894553",
            "2181233851",
            "34352904",
            "171483987",
            "454122399",
            "57415242",
            "19263978",
            "902089998",
            "423540866",
            "2715223320",
            "22185437",
            "17292143",
            "55590247",
            "66757066",
            "22642626",
            "41604618",
            "87275465",
            "22643259",
            "32414973",
            "73406718",
            "20346956",
            "413422891",
            "45412765",
            "19537303",
            "459511725",
            "30954864",
            "21308488",
            "18552281",
            "19924520",
            "24903350",
            "851142163",
            "26270913",
            "20444254",
            "26074296",
            "6395222",
            "15537451",
            "28672101",
            "38053254",
            "24925573",
            "19564719",
            "18164425",
            "22815383",
            "20196159"
          ],
          "id": "929wbl6ymlfk",
          "created_at": "2019-11-08T21:12:47Z",
          "updated_at": "2021-03-09T20:36:44Z",
          "videos_monetized_in_last_thirty_days": 2446
        },
        {
          "name": "Personnalités du jeu vidéo",
          "description": "Diffusez à côté du meilleur contenu quotidien de gaming, exclusivement à partir d’une liste de certains des plus grands et des plus appréciés créateurs numériques du jeu en ligne.",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "90779436",
            "268270621",
            "567167802",
            "246596682",
            "474919140",
            "284422688",
            "185909682",
            "4767225325",
            "2559865245",
            "186888760",
            "161418822",
            "141021153",
            "352881953",
            "1117931702",
            "146556805",
            "357294577",
            "234526497",
            "266687361",
            "214201922",
            "9451052",
            "2163885564",
            "2231422037",
            "116952434",
            "399909209",
            "15993650",
            "974356091193741312",
            "210839744",
            "2313002094",
            "159916388",
            "3258981481",
            "231992478",
            "182236262",
            "386884916",
            "22705686",
            "4140881832",
            "995979576",
            "2244953047",
            "311775629",
            "98821255",
            "2733210014",
            "2741078150"
          ],
          "id": "94ngssfrr01x",
          "created_at": "2019-12-02T20:45:12Z",
          "updated_at": "2021-03-09T20:18:13Z",
          "videos_monetized_in_last_thirty_days": 448
        },
        {
          "name": "Base-ball",
          "description": "Diffusez à côté du meilleur contenu quotidien de base-ball, incluant des équipes universitaires, des équipes professionnelles et les principaux médias sportifs proposant une couverture majeure du base-ball.",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "22016177",
            "22798877",
            "52803520",
            "20710218",
            "423532170",
            "28603812",
            "41144996",
            "22819823",
            "39389304",
            "252273678",
            "123307490",
            "2319354187",
            "41488578",
            "37947138",
            "302066953",
            "159143990",
            "35006336",
            "53178109",
            "40918816",
            "39682297",
            "39397148",
            "39419180",
            "53197137",
            "52863923",
            "21407926",
            "31164229",
            "19607400",
            "39392910",
            "241544156",
            "43024351",
            "37837907",
            "165764237",
            "69117905",
            "87673496",
            "23043294",
            "52824038",
            "52861612",
            "33137450",
            "30008146",
            "39367703",
            "21436663",
            "188575356",
            "40931019",
            "41468683",
            "40927173",
            "172742915"
          ],
          "id": "9lav5usxfmdc",
          "created_at": "2020-05-18T20:20:27Z",
          "updated_at": "2021-03-09T20:37:46Z",
          "videos_monetized_in_last_thirty_days": 190
        },
        {
          "name": "Équipes d’esport",
          "description": "Diffusez à côté des programmes des meilleures équipes d’esport au monde, couvrant à la fois la couverture en direct des événements et d’autres programmations complémentaires tout au long de l’année.",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "759527448757215232",
            "61933836",
            "477213534",
            "907193396049182720",
            "895382891408089089",
            "862708050116976640",
            "115038550",
            "3182089458",
            "4131266472",
            "1145702070961496065",
            "2262070855",
            "920664872786059264",
            "1035653581683220481",
            "14229141",
            "1101275970995027968",
            "20734751",
            "1452520626",
            "720303639277928448",
            "2853641871",
            "912696400571486208",
            "874362688939413504",
            "286505380",
            "892808605170245632",
            "875087838613733376",
            "238431491",
            "867053221940011014",
            "964529942",
            "1172506293174710272",
            "535756639",
            "2255226817",
            "1100825469853696000",
            "1122713320086220803",
            "1124064709295128581",
            "899858978418642944",
            "864977592532688896",
            "864476897106898944",
            "862770685445361665",
            "257268592"
          ],
          "id": "9ys3jz3ktreo",
          "created_at": "2020-10-01T20:02:35Z",
          "updated_at": "2021-03-09T20:36:20Z",
          "videos_monetized_in_last_thirty_days": 169
        },
        {
          "name": "Football",
          "description": "Diffusez à côté du meilleur contenu quotidien de football, incluant des équipes universitaires, des équipes professionnelles et les principaux médias sportifs partageant des vidéos de football en saison et hors saison.",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "21790466",
            "53103297",
            "23642374",
            "817416193854283776",
            "43403778",
            "24179879",
            "26813914",
            "36375662",
            "33587536",
            "180884045",
            "16332223",
            "27902825",
            "180503626",
            "44468807",
            "18336787",
            "818431566",
            "22146282",
            "31126587",
            "40358743",
            "35865630",
            "16347506",
            "72665816",
            "33583496",
            "389038362",
            "36155311",
            "227342532",
            "2151130166",
            "26791995",
            "44666348",
            "24109979",
            "31504542",
            "713143",
            "423536031",
            "25545388",
            "59471027",
            "706923475",
            "19383279",
            "8824902",
            "1655877529",
            "18734310",
            "240734425",
            "17076218",
            "47964412",
            "2802184770",
            "19426729",
            "56443153",
            "23508439",
            "25084916",
            "764347046",
            "19853312",
            "348590880"
          ],
          "id": "8tujg1lvi8sn",
          "created_at": "2019-08-15T20:48:51Z",
          "updated_at": "2021-03-09T20:34:13Z",
          "videos_monetized_in_last_thirty_days": 254
        },
        {
          "name": "Culture et lifestyle (hommes)"
          "description": "Diffusez à côté de contenus issus d’une sélection de comptes, établie selon le profil de leurs abonnés, pour vous aider à toucher une audience majoritairement masculine, dont certains des principaux comptes qui partagent des contenus technologiques, d’actualité et de lifestyle."
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "17764377",
            "61933836",
            "28370738",
            "3224616765",
            "22819823",
            "18927441",
            "734826612684783616",
            "14372486",
            "7157132",
            "15764136",
            "590316679",
            "7302282",
            "895014043932540928",
            "7517222",
            "3489420013",
            "14063426",
            "72665816",
            "214201922",
            "14980903",
            "22199141",
            "21272440",
            "25319414",
            "119593082",
            "4760694445",
            "765905855195803648",
            "238431491",
            "22178780",
            "241544156",
            "25093616",
            "16877611",
            "22146985",
            "368703433",
            "14342661",
            "415605847",
            "2181233851",
            "890891",
            "15764001",
            "614754689",
            "18479513",
            "23508439",
            "348590880"
          ],
          "id": "8tujj1ep7t34",
          "created_at": "2019-08-15T20:49:47Z",
          "updated_at": "2021-03-09T20:39:00Z",
          "videos_monetized_in_last_thirty_days": 1330
        },
        {
          "name": "Culture et lifestyle (femmes)"
          "description": "Diffusez à côté de contenus issus d’une sélection de comptes, établie selon le profil de leurs abonnés, pour vous aider à toucher une audience majoritairement féminine, dont certains des principaux comptes qui partagent des contenus de pop culture, d’actualité et de lifestyle."
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "23482952",
            "20177423",
            "19074134",
            "15566901",
            "32469566",
            "19784831",
            "16145224",
            "16932962",
            "14934818",
            "29730065",
            "24190981",
            "30278532",
            "15846407",
            "24994219",
            "23993734",
            "40965341",
            "16312576",
            "75094638",
            "549673665",
            "18806753",
            "75306892",
            "1482663290",
            "31181674",
            "971407531972186112",
            "4020532937",
            "25087685",
            "22515362",
            "80943051",
            "19247844",
            "15279429",
            "16824090",
            "20710809",
            "979831113655996416",
            "32432308",
            "19472585",
            "25589776",
            "739963476370673665",
            "20188834",
            "926269727663673349"
          ],
          "id": "8tujl1p3yn0g",
          "created_at": "2019-08-15T20:50:24Z",
          "updated_at": "2021-03-09T20:17:53Z",
          "videos_monetized_in_last_thirty_days": 1365
        },
        {
          "name": "Léger"
          "description": "Diffusez à côté d’une liste de comptes sélectionnés pour le volume de contenus positifs et réconfortants et de conversations qu’ils génèrent régulièrement sur X."
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "20177423",
            "22449367",
            "9695312",
            "19074134",
            "4805771380",
            "32469566",
            "1212860112047460352",
            "16402507",
            "16932962",
            "14934818",
            "17446621",
            "29730065",
            "15846407",
            "1604444052",
            "180066380",
            "16312576",
            "549673665",
            "18806753",
            "16211434",
            "545336345",
            "971407531972186112",
            "4020532937",
            "833612154",
            "22515362",
            "20710809",
            "32432308",
            "774311630",
            "3073349892",
            "926269727663673349"
          ],
          "id": "9fg8gmz96qdg",
          "created_at": "2020-03-20T19:37:44Z",
          "updated_at": "2021-03-09T19:57:40Z",
          "videos_monetized_in_last_thirty_days": 1395
        },
        {
          "name": "Soccer"
          "description": "Diffusez à côté du meilleur des contenus quotidiens sur le soccer, y compris des équipes universitaires, des équipes professionnelles et les principaux médias sportifs qui couvrent largement le soccer."
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "21677316",
            "20636347",
            "4704552148",
            "14573900",
            "22556296",
            "1415791555",
            "107146095",
            "17288520",
            "213474069",
            "17493398",
            "44990136",
            "452155423",
            "17744542",
            "16303450",
            "2841146601",
            "2413176055",
            "29739264",
            "38580532",
            "953476292913106945",
            "27092557",
            "86356439",
            "34613288",
            "3170659367",
            "119593082",
            "73412535",
            "627586654",
            "15891449",
            "23011345",
            "96951800",
            "15997022",
            "16960789",
            "21919642",
            "102965285",
            "17224076",
            "36432200",
            "1410055968"
          ],
          "id": "9ddrgesiap6o",
          "created_at": "2020-02-28T22:43:26Z",
          "updated_at": "2021-01-26T17:54:55Z",
          "videos_monetized_in_last_thirty_days": 421
        }
      ],
      "total_count": 9
    }

​

GET accounts/:account_id/curated_categories/:curated_category_id

Récupérer les détails d’un curated_category_id spécifique

Chaque curated_category n’est disponible que dans certains pays, indiqués par les country_codes dans la réponse.

URL de la ressource

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

Paramètres

Nom	Description
account_id obligatoire	L’identifiant du compte utilisé. Figure dans le chemin de la ressource et constitue généralement un paramètre obligatoire pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Exemple: 18ce54d4x5t
curated_category_id obligatoire	La référence à la Curated Category utilisée dans la requête. Type: string Exemple: 9ddrgesiap6o

Exemple de requête

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/curated_categories/9ddrgesiap6o

Exemple de réponse

    {
      "request": {
        "params": {
          "id": "9ddrgesiap6o",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "name": "Football",
        "description": "Diffusez aux côtés du meilleur contenu football au quotidien, notamment des équipes universitaires, des équipes professionnelles et des grands médias sportifs qui assurent une couverture majeure du football.",
        "country_codes": [],
        "publisher_user_ids": [
          "21677316",
          "20636347",
          "4704552148",
          "14573900",
          "22556296",
          "1415791555",
          "107146095",
          "17288520",
          "213474069",
          "17493398",
          "44990136",
          "452155423",
          "17744542",
          "16303450",
          "2841146601",
          "2413176055",
          "29739264",
          "38580532",
          "953476292913106945",
          "27092557",
          "86356439",
          "34613288",
          "3170659367",
          "119593082",
          "73412535",
          "627586654",
          "15891449",
          "23011345",
          "96951800",
          "15997022",
          "16960789",
          "21919642",
          "102965285",
          "17224076",
          "36432200",
          "1410055968"
        ],
        "id": "9ddrgesiap6o",
        "created_at": "2020-02-28T22:43:26Z",
        "updated_at": "2021-01-26T17:54:55Z",
        "videos_monetized_in_last_thirty_days": 421
      }
    }

​

Fonctionnalités

Exécuter dans Postman

​

GET accounts/:account_id/features

Récupère l’ensemble des fonctionnalités accordées auxquelles ce compte publicitaire a accès. Les fonctionnalités sont identifiées par une clé descriptive et ne sont exposées sur cet endpoint que si elles sont introduites en bêta ou dans le cadre d’une diffusion limitée et qu’elles sont disponibles dans la X Ads API. Les fonctionnalités qui ne répondent pas à ces critères ne seront pas exposées sur cet endpoint.

Remarque : Cet endpoint a pour but de favoriser le développement de l’écosystème de la X Ads API en améliorant la visibilité sur l’accès des clients aux versions bêta. Les développeurs d’API ne peuvent pas demander l’accès à des fonctionnalités au nom d’un annonceur. Ces demandes ne peuvent être effectuées que par l’annonceur auprès de son account manager X.

Resource URL

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

Parameters

Name	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’Advertiser API, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: 18ce54d4x5t
feature_keys optional	Paramètre optionnel permettant d’interroger une clé de fonctionnalité spécifique. Les requêtes peuvent inclure plusieurs clés séparées par des virgules. Remarque : Seules les fonctionnalités accessibles par ce compte seront incluses dans la réponse. Type: enum Possible values: REACH_AND_FREQUENCY_ANALYTICS, REACH_FREQUENCY_CAP, WEBSITE_CLICKS_CPM_BILLING

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/features

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t"
        }
      },
      "data": [
        "CIBLAGE_PAR_VILLE",
        "CARTE_DE_CONVERSATION",
        "SONDAGES_MÉDIATIQUES_PROMUS",
        "ANALYTIQUES_PORTÉE_ET_FRÉQUENCE",
        "PLAFOND_DE_FRÉQUENCE_DE_PORTÉE",
        "JUMELAGE_UNIVERSEL"
      ]
    }

​

POST accounts/:account_id/features

SANDBOX UNIQUEMENT

Ajouter une fonctionnalité à un compte sandbox.

La liste à jour des fonctionnalités de compte peut être obtenue via l’endpoint GET accounts/:account_id/features.

URL de ressource

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

Paramètres

Nom	Description
account_id obligatoire	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : gq180y
feature_keys obligatoire	Une liste, séparée par des virgules, de fonctionnalités de compte à ajouter au compte. Type : enum Valeurs possibles : AGE_TARGETING, ALLOW_SKIPPABLE_VIDEOS_FOR_PREROLL_VIEWS_OBJECTIVE, AWARENESS_OBJECTIVE, BRAND_TPN, CHARGE_FOR_GOOD_CLICK, CONVERSATION_CARD, CONVERSATION_CARD_FOUR_OPTIONS, CONVERSATION_CARD_UNLOCK, CPI_CHARGING, DIRECT_MESSAGE_CARD, DR_TAP, ENGAGER_RETARGETING, EVENT_TARGETING, INSTALLED_APP_CATEGORY_TARGETING, MOBILE_CONVERSION_TRANSACTION_VALUE, OPTIMIZED_ACTION_BIDDING, REACH_AND_FREQUENCY_ANALYTICS, REACH_FREQUENCY_CAP, VALIDATED_AGE_TARGETING, VIDEO_VIEWS_MIDROLL_OBJECTIVE, PREROLL_VIEWS_OBJECTIVE, VIDEO_APP_DOWNLOAD_CARD

Exemple de requête

POST https://ads-api-sandbox.x.com/12/accounts/gq180y/features?feature_keys=VALIDATED_AGE_TARGETING

Exemple de réponse

    {
      "request": {
        "params": {
          "account_id": "gq180y",
          "feature_keys": [
            "VALIDATED_AGE_TARGETING"
          ]
        }
      },
      "data": [
        "ALLOW_SKIPPABLE_VIDEOS_FOR_PREROLL_VIEWS_OBJECTIVE",
        "AWARENESS_OBJECTIVE",
        "CPI_CHARGING",
        "EVENT_TARGETING",
        "INSTALLED_APP_CATEGORY_TARGETING",
        "MOBILE_CONVERSION_TRANSACTION_VALUE",
        "OPTIMIZED_ACTION_BIDDING",
        "VALIDATED_AGE_TARGETING",
        "VIDEO_APP_DOWNLOAD_CARD"
      ]
    }

​

DELETE accounts/:account_id/features

SANDBOX UNIQUEMENT

Supprime une fonctionnalité d’un compte sandbox.

La liste à jour des fonctionnalités de compte peut être obtenue via l’endpoint GET accounts/:account_id/features.

Resource URL

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

Parameters

Name	Description
account_id required	Identifiant du compte utilisé. Figure dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: gq180y
feature_keys required	Liste, séparée par des virgules, des fonctionnalités de compte à retirer du compte. Type: enum Possible values: AGE_TARGETING, ALLOW_SKIPPABLE_VIDEOS_FOR_PREROLL_VIEWS_OBJECTIVE, AWARENESS_OBJECTIVE, BRAND_TPN, CHARGE_FOR_GOOD_CLICK, CONVERSATION_CARD, CONVERSATION_CARD_FOUR_OPTIONS, CONVERSATION_CARD_UNLOCK, CPI_CHARGING, DIRECT_MESSAGE_CARD, DR_TAP, ENGAGER_RETARGETING, EVENT_TARGETING, INSTALLED_APP_CATEGORY_TARGETING, MOBILE_CONVERSION_TRANSACTION_VALUE, OPTIMIZED_ACTION_BIDDING, REACH_AND_FREQUENCY_ANALYTICS, REACH_FREQUENCY_CAP, VALIDATED_AGE_TARGETING, VIDEO_VIEWS_MIDROLL_OBJECTIVE, PREROLL_VIEWS_OBJECTIVE, VIDEO_APP_DOWNLOAD_CARD

Example Request

DELETE https://ads-api-sandbox.x.com/12/accounts/gq180y/features?feature_keys=PREROLL_VIEWS_OBJECTIVE

Example Response

    {
      "request": {
        "params": {
          "account_id": "gq180y",
          "feature_keys": [
            "PREROLL_VIEWS_OBJECTIVE"
          ]
        }
      },
      "data": [
        "CPI_CHARGING",
        "EVENT_TARGETING",
        "INSTALLED_APP_CATEGORY_TARGETING",
        "MOBILE_CONVERSION_TRANSACTION_VALUE",
        "OPTIMIZED_ACTION_BIDDING",
        "VIDEO_APP_DOWNLOAD_CARD"
      ]
    }

​

Instruments de financement

Exécuter dans Postman

​

GET accounts/:account_id/funding_instruments

Récupère les détails de certains ou de tous les instruments de financement associés au compte actuel.

URL de la ressource

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

Paramètres

Name	Description
account_id required	L’identifiant du compte levier. Figure dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: 18ce54d4x5t
count optional	Spécifie le nombre d’enregistrements à tenter de récupérer par requête distincte. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Spécifie un curseur pour obtenir la page de résultats suivante. Voir Pagination pour plus d’informations. Type: string Example: 8x7v00oow
funding_instrument_ids optional	Restreint la réponse aux instruments de financement souhaités en spécifiant une liste d’identifiants séparés par des virgules. Jusqu’à 200 ID peuvent être fournis. Type: string Example: lygyi
sort_by optional	Trie selon un attribut pris en charge, par ordre croissant ou décroissant. Voir Sorting pour plus d’informations. Type: string Example: created_at-asc
with_deleted optional	Inclure les résultats supprimés dans la requête. Type: boolean Default: false Possible values: true, false
with_total_count optional	Inclure l’attribut de réponse total_count. Remarque : Ce paramètre et cursor sont exclusifs. Remarque : Les requêtes incluant total_count auront des limites de taux plus basses, actuellement fixées à 200 par 15 minutes. Type: boolean Default: false Possible values: true, false

Exemple de requête

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/funding_instruments

Exemple de réponse

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "start_time": "2016-07-22T04:24:04Z",
          "description": "Visa finissant en 0650",
          "credit_limit_local_micro": 200000000,
          "end_time": null,
          "id": "lygyi",
          "entity_status": "ACTIVE",
          "account_id": "18ce54d4x5t",
          "reasons_not_able_to_fund": [],
          "io_header": null,
          "currency": "USD",
          "funded_amount_local_micro": 645940000,
          "created_at": "2016-07-22T04:24:04Z",
          "type": "CREDIT_CARD",
          "able_to_fund": true,
          "updated_at": "2017-04-05T00:25:13Z",
          "credit_remaining_local_micro": null,
          "deleted": false
        }
      ]
    }

​

GET accounts/:account_id/funding_instruments/:funding_instrument_id

Récupère un instrument de financement spécifique associé au compte actuel.

URL de la ressource

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

Paramètres

Nom	Description
account_id requis	L’identifiant du compte à effet de levier. Figure dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte indiqué doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
funding_instrument_id requis	La référence à l’instrument de financement utilisé dans la requête. Type : string Exemple : lygyi
with_deleted optionnel	Inclure les éléments supprimés dans la réponse. Type : boolean Valeur par défaut : false Valeurs possibles : true, false

Exemple de requête

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/funding_instruments/lygyi

Exemple de réponse

    {
      "request": {
        "params": {
          "funding_instrument_id": "lygyi",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "start_time": "2016-07-22T04:24:04Z",
        "description": "Visa se terminant par 0650",
        "credit_limit_local_micro": 200000000,
        "end_time": null,
        "id": "lygyi",
        "entity_status": "ACTIVE",
        "account_id": "18ce54d4x5t",
        "reasons_not_able_to_fund": [],
        "io_header": null,
        "currency": "USD",
        "funded_amount_local_micro": 645940000,
        "created_at": "2016-07-22T04:24:04Z",
        "type": "CREDIT_CARD",
        "able_to_fund": true,
        "updated_at": "2017-04-05T00:25:13Z",
        "credit_remaining_local_micro": null,
        "deleted": false
      }
    }

​

POST accounts/:account_id/funding_instruments

SANDBOX UNIQUEMENT

Créer un instrument de financement dans l’environnement sandbox.

Il n’y a aucun risque d’engendrer des coûts lors de l’utilisation d’un instrument de financement sandbox.

URL de la ressource

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

Paramètres

Name	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin d’accès de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: gq1844
currency required	La devise, exprimée selon la norme ISO 4217. Type: string Example: USD
start_time required	La date à laquelle l’instrument de financement devient actif et utilisable, exprimée au format ISO 8601. Type: string Example: 2017-05-19T07:00:00Z
type required	Le type d’instrument de financement à créer. Type: enum Valeurs possibles : AGENCY_CREDIT_LINE, CREDIT_CARD, CREDIT_LINE, INSERTION_ORDER, PARTNER_MANAGED
end_time sometimes required	La date à laquelle l’instrument de financement devient inactif, exprimée au format ISO 8601. Type: string Example: 2017-05-26T07:00:00Z
credit_limit_local_micro optional	Le crédit total disponible pour cet instrument de financement. Remarque : applicable uniquement à certains types d’instruments de financement. Type: long Example: 37500000
funded_amount_local_micro optional	Le budget total alloué à cet instrument de financement. Remarque : applicable uniquement à certains types d’instruments de financement. Type: long Example: 37500000

Exemple de requête

POST https://ads-api-sandbox.x.com/12/accounts/gq1844/funding_instruments?currency=USD&start_time=2017-07-10T00:00:00Z&type=INSERTION_ORDER&end_time=2018-01-10T00:00:00Z&funded_amount_local_micro=140000000000

Exemple de réponse

    {
      "data": {
        "start_time": "2017-07-10T00:00:00Z",
        "description": "(aucune méthode de paiement n'a encore été configurée)",
        "credit_limit_local_micro": null,
        "end_time": "2018-01-10T00:00:00Z",
        "id": "hxtet",
        "entity_status": "ACTIVE",
        "account_id": "gq1844",
        "reasons_not_able_to_fund": [],
        "io_header": null,
        "currency": "USD",
        "funded_amount_local_micro": 140000000000,
        "created_at": "2017-09-09T05:23:28Z",
        "type": "INSERTION_ORDER",
        "able_to_fund": true,
        "updated_at": "2017-09-09T05:23:28Z",
        "credit_remaining_local_micro": null,
        "deleted": false
      },
      "request": {
        "params": {
          "start_time": "2017-07-10T00:00:00Z",
          "end_time": "2018-01-10T00:00:00Z",
          "account_id": "gq1844",
          "currency": "USD",
          "funded_amount_local_micro": 140000000000,
          "type": "INSERTION_ORDER"
        }
      }
    }

​

DELETE accounts/:account_id/funding_instruments/:funding_instrument_id

SANDBOX UNIQUEMENT

Supprime un instrument de financement dans l’environnement sandbox.

Resource URL

https://ads-api-sandbox.x.com/12/accounts/:account_id/funding_instruments/:funding_instrument_id

Parameters

Name	Description
account_id required	L’identifiant du compte à effet de levier. Apparaît dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Exemple : gq1844
funding_instrument_id required	La référence à l’instrument de financement concerné par la requête. Type: string Exemple : hxt82

Example Request

DELETE https://ads-api-sandbox.x.com/12/accounts/gq1844/funding_instruments/hxt82

Example Response

    {
      "data": {
        "start_time": "2017-08-30T19:23:47Z",
        "description": "(aucun moyen de paiement n'a encore été configuré)",
        "credit_limit_local_micro": 500000000,
        "end_time": null,
        "id": "hxt82",
        "entity_status": "ACTIVE",
        "account_id": "gq1844",
        "reasons_not_able_to_fund": [
          "DELETED"
        ],
        "io_header": null,
        "currency": "USD",
        "funded_amount_local_micro": null,
        "created_at": "2017-08-30T19:23:47Z",
        "type": "CREDIT_CARD",
        "able_to_fund": false,
        "updated_at": "2017-09-09T02:08:30Z",
        "credit_remaining_local_micro": null,
        "deleted": true
      },
      "request": {
        "params": {
          "funding_instrument_id": "hxt82",
          "account_id": "gq1844"
        }
      }
    }

​

Catégories IAB

Exécuter dans Postman

​

GET iab_categories

Récupère les categories d’App valides pour les groupes d’annonces (line_items).

Resource URL

https://ads-api.x.com/12/iab_categories

Parameters

Name	Description
count optional	Indique le nombre d’enregistrements à tenter de récupérer par requête distincte. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Indique un curseur pour obtenir la page suivante de catégories. Voir Pagination pour plus d’informations. Type: string Example: gc-ddf4a
with_total_count optional	Inclut l’attribut de réponse total_count. Note : Ce paramètre et cursor sont mutuellement exclusifs. Note : Les requêtes incluant total_count sont soumises à des limites de taux plus basses, actuellement fixées à 200 par 15 minutes. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/iab_categories?count=2

Example Response

    {
      "data": [
        {
          "id": "IAB1",
          "parent_id": null,
          "name": "Arts et divertissement"
        },
        {
          "id": "IAB1-1",
          "parent_id": "IAB1",
          "name": "Livres et littérature"
        }
      ],
      "next_cursor": "uxa8",
      "request": {
        "params": {
          "count": 2
        }
      }
    }

​

Éléments de campagne

Exécuter dans Postman

​

GET accounts/:account_id/line_items

Récupère les détails de certains ou de l’ensemble des line items associés au compte actuel.

Resource URL

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

Parameters

Name	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: 18ce54d4x5t
campaign_ids optional	Limite la réponse aux seuls line items rattachés à des campagnes spécifiques en indiquant une liste d’identifiants séparés par des virgules. Jusqu’à 200 IDs peuvent être fournis. Type: string Example: 8gdx6
count optional	Spécifie le nombre d’enregistrements à tenter de récupérer par requête distincte. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Spécifie un curseur pour obtenir la page suivante de résultats. Voir Pagination pour plus d’informations. Type: string Example: 8x7v00oow
funding_instrument_ids optional	Limite la réponse aux seuls line items rattachés à des instruments de financement spécifiques en indiquant une liste d’identifiants séparés par des virgules. Jusqu’à 200 IDs peuvent être fournis. Type: string Example: lygyi
line_item_ids optional	Limite la réponse aux seuls line items souhaités en indiquant une liste d’identifiants séparés par des virgules. Jusqu’à 200 IDs peuvent être fournis. Type: string Example: 8v7jo
q optional	Une query facultative pour filtrer la ressource par name. Type: string Min, Max length: 1, 255
sort_by optional	Trie selon un attribut pris en charge, par ordre croissant ou décroissant. Voir Sorting pour plus d’informations. Type: string Example: created_at-asc
with_deleted optional	Inclure les résultats supprimés dans votre requête. Type: boolean Default: false Possible values: true, false
with_draft optional	Inclure les résultats des campagnes à l’état de brouillon dans votre requête. Type: boolean Default: false Possible values: true, false
with_total_count optional	Inclure l’attribut de réponse total_count. Note : Ce paramètre et cursor sont exclusifs. Note : Les requêtes qui incluent total_count auront des limites de taux plus faibles, actuellement fixées à 200 par 15 minutes. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items?line_item_ids=itttx

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "line_item_ids": [
            "itttx"
          ]
        }
      },
      "next_cursor": null,
      "data": [
        {
          "advertiser_user_id": "756201191646691328",
          "name": "li-18",
          "placements": [
            "ALL_ON_TWITTER"
          ],
          "start_time": "2021-02-16T00:00:00Z",
          "bid_amount_local_micro": 320000,
          "advertiser_domain": null,
          "target_cpa_local_micro": null,
          "primary_web_event_tag": null,
          "goal": "ENGAGEMENT",
          "daily_budget_amount_local_micro": null,
          "product_type": "PROMOTED_TWEETS",
          "end_time": null,
          "funding_instrument_id": "lygyi",
          "bid_strategy": "MAX",
          "duration_in_days": null,
          "standard_delivery": null,
          "total_budget_amount_local_micro": null,
          "objective": "ENGAGEMENTS",
          "id": "itttx",
          "entity_status": "PAUSED",
          "automatic_tweet_promotion": null,
          "frequency_cap": null,
          "android_app_store_identifier": null,
          "categories": [],
          "currency": "USD",
          "pay_by": "ENGAGEMENT",
          "created_at": "2021-02-23T23:37:54Z",
          "ios_app_store_identifier": null,
          "updated_at": "2022-06-01T02:01:18Z",
          "campaign_id": "f4z6x",
          "creative_source": "MANUAL",
          "deleted": false
        }
      ]
    }

​

GET accounts/:account_id/line_items/:line_item_id

Récupérer un élément de ligne spécifique associé au compte en cours.

URL de la ressource

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

Paramètres

Nom	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Exemple: 18ce54d4x5t
line_item_id required	La référence de l’élément de ligne ciblé par la requête. Type: string Exemple: 8v7jo
with_deleted optional	Inclure les résultats supprimés dans la réponse. Type: boolean Valeur par défaut: false Valeurs possibles: true, false

Exemple de requête

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items/itttx

Exemple de réponse

    {
      "request": {
        "params": {
          "line_item_id": "itttx",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "advertiser_user_id": "756201191646691328",
        "name": "li-18",
        "placements": [
          "ALL_ON_TWITTER"
        ],
        "start_time": "2021-02-16T00:00:00Z",
        "bid_amount_local_micro": 320000,
        "advertiser_domain": null,
        "target_cpa_local_micro": null,
        "primary_web_event_tag": null,
        "goal": "ENGAGEMENT",
        "daily_budget_amount_local_micro": null,
        "product_type": "PROMOTED_TWEETS",
        "end_time": null,
        "funding_instrument_id": "lygyi",
        "bid_strategy": "MAX",
        "duration_in_days": null,
        "standard_delivery": null,
        "total_budget_amount_local_micro": null,
        "objective": "ENGAGEMENTS",
        "id": "itttx",
        "entity_status": "PAUSED",
        "automatic_tweet_promotion": null,
        "frequency_cap": null,
        "android_app_store_identifier": null,
        "categories": [],
        "currency": "USD",
        "pay_by": "ENGAGEMENT",
        "created_at": "2021-02-23T23:37:54Z",
        "ios_app_store_identifier": null,
        "updated_at": "2022-06-01T02:01:18Z",
        "campaign_id": "f4z6x",
        "creative_source": "MANUAL",
        "deleted": false
      }
    }

​

POST accounts/:account_id/line_items

Créer un poste de dépense (line item) associé à la campagne spécifiée appartenant au compte actuel.

Tous les postes de dépense d’une campagne doivent partager le même product_type et le même objective.

Lorsque vous utilisez le type de produit PROMOTED_ACCOUNT, associer un Tweet au line_item ajoutera des emplacements dans le fil sur mobile en plus de l’emplacement standard PROMOTED_ACCOUNT.

Renseigner android_app_store_identifier ou ios_app_store_identifier ajoutera automatiquement les critères de ciblage correspondant à l’app mobile promue pour ce poste de dépense ; par exemple, fournir ios_app_store_identifier ajoutera le critère de ciblage PLATFORM pour iOS (options de ciblage).

Remarque : la limite est de 100 postes de dépense par campagne et de 256 postes de dépense actifs sur l’ensemble des campagnes.

Resource URL

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

Parameters

Nom	Description
account_id requis	L’identifiant du compte exploité. Apparaît dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Advertiser à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
campaign_id requis	L’identifiant de la campagne sous laquelle créer l’élément de ligne. Type : string Exemple : 8slvg
end_time requis	L’heure, exprimée au format ISO 8601, à laquelle l’élément de ligne cessera d’être diffusé. Type : string Exemple : 2017-10-05T00:00:00Z
objective requis	L’objectif de campagne pour cet élément de ligne. Type : enum Valeurs possibles : APP_ENGAGEMENTS, APP_INSTALLS, REACH, FOLLOWERS, ENGAGEMENTS, VIDEO_VIEWS, PREROLL_VIEWS, WEBSITE_CLICKS
placements requis	L’emplacement ou les emplacements de diffusion pour cet élément de ligne. Spécifiez une liste de valeurs d’emplacement séparées par des virgules. Type : enum Valeurs possibles : ALL_ON_TWITTER, PUBLISHER_NETWORK, TAP_BANNER, TAP_FULL, TAP_FULL_LANDSCAPE, TAP_NATIVE, TAP_MRECT,TWITTER_PROFILE, TWITTER_REPLIES, TWITTER_SEARCH, TWITTER_TIMELINE
product_type requis	Le type de produit promu que contiendra cet élément de ligne. Type : enum Valeurs possibles : MEDIA, PROMOTED_ACCOUNT, PROMOTED_TWEETS
start_time requis	L’heure, exprimée au format ISO 8601, à laquelle l’élément de ligne commencera à être diffusé. Type : string Exemple : 2017-07-05T00:00:00Z
advertiser_domain parfois requis	Le domaine du site web pour cet annonceur, sans la spécification du protocole. Remarque : Requis lorsque l’emplacement de l’élément de ligne est défini sur PUBLISHER_NETWORK. Type : string Exemple : x.com
android_app_store_identifier parfois requis	L’identifiant Google Play Store pour les applications promues. Remarque : Les objectifs APP_INSTALLS et APP_ENGAGEMENTS nécessitent de définir au moins un identifiant d’app store — soit android_app_store_identifier soit ios_app_store_identifier. Type : string Exemple : com.twitter.android
bid_amount_local_micro parfois requis	Le montant d’enchère à associer à cet élément de ligne. La devise associée à l’instrument de financement spécifié sera utilisée. Pour USD, 5,50 $ est représenté comme 5500000. Remarque : Requis si bid_strategy est défini sur MAX ou TARGET Remarque : Seules les valeurs supérieures à zéro sont acceptées. Type : long Exemple : 5500000
categories parfois requis	Les catégories IAB pertinentes pour cet annonceur. Voir GET iab_categories. Remarque : Requis lorsque l’emplacement de l’élément de ligne est défini sur PUBLISHER_NETWORK. Type : string Exemple : IAB3-1
ios_app_store_identifier parfois requis	La partie numérique de l’identifiant Apple App Store pour les applications promues. Remarque : Les objectifs APP_INSTALLS et APP_ENGAGEMENTS nécessitent de définir au moins un identifiant d’app store — soit android_app_store_identifier soit ios_app_store_identifier. Type : string Exemple : 333903271
primary_web_event_tag parfois requis	L’identifiant de la balise d’événement web principale. Permet un suivi plus précis des engagements pour la campagne concernant cet élément de ligne. Remarque : Requis lorsque l’objectif de l’élément de ligne est défini sur WEBSITE_CONVERSIONS. Type : string Exemple : nvo4z
advertiser_user_id optionnel	L’identifiant utilisateur X pour le compte promouvant une publicité PREROLL_VIEWS. Seules certaines applications clientes peuvent utiliser ce paramètre. Type : string Exemple : 312226591
audience_expansion optionnel	Utilisé pour étendre la portée des campagnes en ciblant des utilisateurs similaires à ceux déjà ciblés. Remarque : Par défaut, aucune expansion ne sera appliquée. Type : enum Valeurs possibles : BROAD, DEFINED, EXPANDED
bid_strategy optionnel	Le mécanisme d’enchères. AUTO optimise automatiquement les enchères en fonction du budget quotidien et des dates de diffusion de campagne. MAX définit l’enchère maximale autorisée et n’est pas disponible lorsque l’objectif est défini sur REACH ou FOLLOWERS. TARGET tente de maintenir les moyennes d’enchères quotidiennes dans les 20 % du bid_amount_local_micro spécifié et est disponible lorsque l’objectif est défini sur REACH, FOLLOWERS, ou WEBSITE_CLICKS. Remarque : Si défini sur AUTO, bid_amount_local_micro sera ignoré. Remarque : Valeur par défaut basée sur l’objectif. Type : enum Valeurs possibles : AUTO, MAX, TARGET
duration_in_days optionnel	La période de temps dans laquelle le frequency_cap est atteint. Type : int Valeurs possibles : 1, 7, 30
entity_status optionnel	Le statut de l’élément de ligne. Type : enum Valeur par défaut : ACTIVE Valeurs possibles : ACTIVE, DRAFT, PAUSED
frequency_cap optionnel	Le nombre maximum de fois qu’une publicité peut être diffusée à un utilisateur. Remarque : Pris en charge uniquement pour les objectifs REACH, ENGAGEMENTS, VIDEO_VIEWS, et PREROLL_VIEWS. Type : int Exemple : 5
goal optionnel	Le paramètre d’optimisation à utiliser avec cet élément de ligne. L’option APP_PURCHASES est disponible pour APP_INSTALL. Les options APP_CLICKS et APP_INSTALLS sont disponibles pour les objectifs APP_INSTALL et APP_ENGAGEMENTS et peuvent nécessiter l’utilisation d’un partenaire MACT pris en charge. L’option SITE_VISITS n’est disponible qu’avec l’objectif WEBSITE_CLICKS. Remarque : Valeur par défaut basée sur l’objectif. Type : enum Valeurs possibles : APP_CLICKS, APP_INSTALLS, APP_PURCHASES,ENGAGEMENT, FOLLOWERS, LINK_CLICKS, MAX_REACH, PREROLL, PREROLL_STARTS, REACH_WITH_ENGAGEMENT, SITE_VISITS, VIDEO_VIEW, VIEW_3S_100PCT, VIEW_6S, VIEW_15S, WEBSITE_CONVERSIONS
name optionnel	Le nom de l’élément de ligne. Type : string Exemple : demo Longueur min, max : 1, 255
pay_by optionnel	L’unité de facturation pour cet élément de ligne. Ce paramètre ne peut être modifié que pour les éléments de ligne utilisant l’objectif APP_INSTALLS. Remarque : La valeur par défaut de pay_by est automatiquement définie en fonction de l’objectif de campagne et de l’unité d’enchère de l’élément de ligne. L’objectif APP_INSTALLS prend en charge les valeurs APP_CLICK et IMPRESSION. IMPRESSION est la valeur par défaut. L’objectif LINK_CLICKS prend en charge les valeurs LINK_CLICK et IMPRESSION. IMPRESSION est la valeur par défaut mais n’est pas prise en charge lors de la définition de TARGET pour bid_strategy. L’objectif SITE_VISITS prend en charge les valeurs IMPRESSION. Type : enum Valeurs possibles : APP_CLICK, IMPRESSION, LINK_CLICK
standard_delivery optionnel	Activer la diffusion standard ou accélérée. Voir Rythme budgétaire pour plus d’informations sur la diffusion standard par rapport à la diffusion accélérée. Disponible uniquement lorsque budget_optimization est défini sur LINE_ITEM pour la campagne parente Type : boolean Par défaut : true Valeurs possibles : true, false
total_budget_amount_local_micro optionnel	Le montant total du budget à allouer à l’élément de ligne. La devise associée à l’instrument de financement spécifié sera utilisée. Pour l’USD, 37,50 $ est représenté par 37500000. Type : long Exemple : 37500000
daily_budget_amount_local_micro parfois requis	Le montant du budget quotidien à allouer à la campagne. La devise associée à l’instrument de financement spécifié sera utilisée. Pour l’USD, 5,50 $ est représenté par 5500000. Lorsqu’il n’est pas fourni, la campagne dépensera de manière uniforme en fonction du budget total et de la durée de diffusion de la campagne. Disponible uniquement lorsque budget_optimization est défini sur LINE_ITEM pour la campagne parente Remarque : Cette valeur doit être inférieure ou égale à total_budget_amount_local_micro. Type : long Exemple : 5500000

Exemple de requête

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items?campaign_id=hwtq0&objective=ENGAGEMENTS&product_type=PROMOTED_TWEETS&placements=ALL_ON_TWITTER&bid_amount_local_micro=3210000&entity_status=PAUSED&daily_budget_amount_local_micro=1000000&start_time=2022-06-15

Exemple de réponse

    {
      "request": {
        "params": {
          "placements": [
            "ALL_ON_TWITTER"
          ],
          "start_time": "2022-06-15T00:00:00Z",
          "bid_amount_local_micro": 3210000,
          "daily_budget_amount_local_micro": 1000000,
          "product_type": "PROMOTED_TWEETS",
          "objective": "ENGAGEMENTS",
          "entity_status": "PAUSED",
          "account_id": "18ce54d4x5t",
          "campaign_id": "hwtq0"
        }
      },
      "data": {
        "advertiser_user_id": "756201191646691328",
        "name": null,
        "placements": [
          "ALL_ON_TWITTER"
        ],
        "start_time": "2022-06-15T00:00:00Z",
        "bid_amount_local_micro": 3210000,
        "advertiser_domain": null,
        "target_cpa_local_micro": null,
        "primary_web_event_tag": null,
        "goal": "ENGAGEMENT",
        "daily_budget_amount_local_micro": 1000000,
        "product_type": "PROMOTED_TWEETS",
        "end_time": null,
        "bid_strategy": "MAX",
        "duration_in_days": null,
        "standard_delivery": true,
        "total_budget_amount_local_micro": null,
        "objective": "ENGAGEMENTS",
        "id": "ml5vs",
        "entity_status": "PAUSED",
        "automatic_tweet_promotion": null,
        "frequency_cap": null,
        "android_app_store_identifier": null,
        "categories": [],
        "currency": "USD",
        "pay_by": "ENGAGEMENT",
        "created_at": "2022-06-03T23:47:20Z",
        "ios_app_store_identifier": null,
        "updated_at": "2022-06-03T23:47:20Z",
        "campaign_id": "hwtq0",
        "creative_source": "MANUAL",
        "deleted": false
      }
    }

​

POST batch/accounts/:account_id/line_items

Permet de créer par lot de nouveaux line items en une seule requête.

Requêtes par lot

• La taille maximale actuelle d’un lot est de 40.
• 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, et toutes les réponses de l’API — en cas d’erreur comme de réussite — conservent l’ordre des éléments de la requête initiale.

Réponses par lot

Les réponses de l’API pour les requêtes par lot renvoient une collection ordonnée d’éléments. Pour le reste, elles sont identiques, dans leur structure, à leurs endpoints correspondants à élément unique.

Erreurs par lot

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

URL de la ressource

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

Paramètres

Name	Description
operation_type requis	Le type d’opération appliqué à chaque élément. Type : enum Valeurs possibles : Create, Delete, Update
params requis	Un objet JSON contenant tous les paramètres des objets line item. Pour la liste des paramètres obligatoires et optionnels des line items, voir ici.

Exemple de requête

POST 'Content-Type: application/json' https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/line_items

    [
      {
        "operation_type":"Create",
        "params":{
          "campaign_id":"8yn7m",
          "objective":"ENGAGEMENTS",
          "product_type":"PROMOTED_TWEETS",
          "placements":"ALL_ON_TWITTER",
          "bid_amount_local_micro":3210000,
          "entity_status":"PAUSED"
        }
      }
    ]

Exemple de réponse

    {
      "data": [
        {
          "advertiser_user_id": "756201191646691328",
          "name": null,
          "placements": [
            "ALL_ON_TWITTER"
          ],
          "start_time": null,
          "bid_amount_local_micro": 3210000,
          "advertiser_domain": null,
          "target_cpa_local_micro": null,
          "primary_web_event_tag": null,
          "goal": "ENGAGEMENT",
          "daily_budget_amount_local_micro": null,
          "product_type": "PROMOTED_TWEETS",
          "end_time": null,
          "funding_instrument_id": "lygyi",
          "bid_strategy": "MAX",
          "duration_in_days": null,
          "standard_delivery": null,
          "total_budget_amount_local_micro": null,
          "objective": "ENGAGEMENTS",
          "id": "9cqi0",
          "entity_status": "PAUSED",
          "automatic_tweet_promotion": null,
          "frequency_cap": null,
          "android_app_store_identifier": null,
          "categories": [],
          "currency": "USD",
          "pay_by": "ENGAGEMENT",
          "created_at": "2017-07-07T17:42:20Z",
          "ios_app_store_identifier": null,
          "updated_at": "2017-07-07T17:42:20Z",
          "campaign_id": "8yn7m",
          "creative_source": "MANUAL",
          "deleted": false
        }
      ],
      "request": [
        {
          "params": {
            "placements": [
              "ALL_ON_TWITTER"
            ],
            "bid_amount_local_micro": 3210000,
            "product_type": "PROMOTED_TWEETS",
            "objective": "ENGAGEMENTS",
            "entity_status": "PAUSED",
            "account_id": "18ce54d4x5t",
            "campaign_id": "8yn7m"
          },
          "operation_type": "Create"
        }
      ]
    }

​

PUT accounts/:account_id/line_items/:line_item_id

Met à jour l’élément de ligne spécifié associé au compte en cours.

URL de la ressource

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

Paramètres

Nom	Description
account_id requis	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Advertiser à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
line_item_id requis	Une référence à l’élément de ligne que vous manipulez dans la requête. Type : string Exemple : 8v7jo
advertiser_domain optionnel	Le domaine du site web de cet annonceur, sans la spécification du protocole. Remarque : Requis lorsque le placement de l’élément de ligne est défini sur PUBLISHER_NETWORK. Type : string Exemple : x.com
advertiser_user_id optionnel	L’identifiant utilisateur X pour le compte qui promeut une publicité PREROLL_VIEWS. Seules certaines applications clientes peuvent utiliser ce paramètre. Type : string Exemple : 312226591
android_app_store_identifier optionnel	L’identifiant Google Play Store pour l’application promue. Remarque : Les objectifs APP_INSTALLS et APP_ENGAGEMENTS nécessitent de définir au moins un identifiant d’app store — soit android_app_store_identifier soit ios_app_store_identifier. Type : string Exemple : com.twitter.android
audience_expansion optionnel	Utilisé pour étendre la portée des campagnes en ciblant des utilisateurs similaires à ceux déjà ciblés. Type : enum Valeurs possibles : BROAD, DEFINED, EXPANDED
bid_amount_local_micro optionnel	Le montant d’enchère à associer à cet élément de ligne. La devise associée à l’instrument de financement spécifié sera utilisée. Pour USD, 5,50 $ est représenté par 5500000. Remarque : Requis si bid_strategy est défini sur MAX ou TARGET Remarque : Seules les valeurs supérieures à zéro sont acceptées. Type : long Exemple : 140000
bid_strategy optionnel	Le mécanisme d’enchères. AUTO optimise automatiquement les enchères en fonction du budget quotidien et des dates de diffusion de campagne. MAX définit l’enchère maximale autorisée et n’est pas disponible lorsque l’objectif est défini sur REACH ou FOLLOWERS. TARGET tente de maintenir les moyennes d’enchères quotidiennes dans les 20 % du bid_amount_local_micro spécifié et est disponible lorsque l’objectif est défini sur REACH ou WEBSITE_CLICKS. Remarque : Si défini sur AUTO, bid_amount_local_micro sera ignoré. Remarque : Valeur par défaut basée sur l’objectif. Type : enum Valeurs possibles : AUTO, MAX, TARGET
categories optionnel	Les catégories IAB pertinentes pour cet annonceur. Voir GET iab_categories. Remarque : Requis lorsque le placement de l’élément de ligne est défini sur PUBLISHER_NETWORK. Type : string Exemple : IAB3-1
duration_in_days optionnel	La période de temps pendant laquelle le frequency_cap est atteint. Type : int Valeurs possibles : 1, 7, 30
entity_status optionnel	Le statut de l’élément de ligne. Type : enum Valeurs possibles : ACTIVE, PAUSED
end_time optionnel	L’heure, exprimée au format ISO 8601, à laquelle l’élément de ligne cessera d’être diffusé. Type : string Exemple : 2017-10-05T00:00:00Z
frequency_cap optionnel	Le nombre maximum de fois qu’une publicité peut être diffusée à un utilisateur. Remarque : Pris en charge uniquement pour les objectifs REACH, ENGAGEMENTS, VIDEO_VIEWS et PREROLL_VIEWS. Type : int Exemple : 5
goal optionnel	Le paramètre d’optimisation à utiliser avec cet élément de ligne. L’option APP_PURCHASES est disponible pour APP_INSTALL. Les options APP_CLICKS et APP_INSTALLS sont disponibles pour APP_INSTALL et APP_ENGAGEMENTS et peuvent nécessiter l’utilisation d’un partenaire MACT pris en charge. Remarque : Valeur par défaut basée sur l’objectif. Type : enum Valeurs possibles : APP_CLICKS, APP_INSTALLS, APP_PURCHASES, ENGAGEMENT, FOLLOWERS, LINK_CLICKS, MAX_REACH, PREROLL, PREROLL_STARTS, REACH_WITH_ENGAGEMENT, VIDEO_VIEW, VIEW_3S_100PCT, VIEW_6S, VIEW_15S, WEBSITE_CONVERSIONS
ios_app_store_identifier optionnel	La partie numérique de l’identifiant Apple App Store pour les applications promues. Remarque : Les objectifs APP_INSTALLS et APP_ENGAGEMENTS nécessitent de définir au moins un identifiant d’app store — soit android_app_store_identifier soit ios_app_store_identifier. Type : string Exemple : 333903271
name optionnel	Le nom de l’élément de ligne. Type : string Exemple : demo
pay_by optionnel	L’unité de facturation pour cet élément de ligne. Ce paramètre ne peut être modifié que pour les éléments de ligne utilisant l’objectif APP_INSTALLS. Remarque : La valeur pay_by par défaut est automatiquement définie en fonction de l’objectif de campagne et de l’unité d’enchère de l’élément de ligne. L’objectif APP_INSTALLS prend en charge les valeurs APP_CLICK et IMPRESSION. IMPRESSION est la valeur par défaut. L’objectif LINK_CLICKS prend en charge les valeurs LINK_CLICK et IMPRESSION. IMPRESSION est la valeur par défaut mais n’est pas pris en charge lors de la définition de TARGET pour bid_strategy. L’objectif SITE_VISITS prend en charge les valeurs IMPRESSION. Type : enum Valeurs possibles : APP_CLICK, IMPRESSION, LINK_CLICK
start_time optionnel	L’heure, exprimée au format ISO 8601, à laquelle l’élément de ligne commencera à être diffusé. Type : string Exemple : 2017-07-05T00:00:00Z
total_budget_amount_local_micro optionnel	Le montant total du budget à allouer à l’élément de ligne. La devise associée à l’instrument de financement spécifié sera utilisée. Pour USD, 37,50 $ est représenté par 37500000. Type : long Exemple : 37500000
daily_budget_amount_local_micro optionnel	Le montant du budget quotidien à allouer à la campagne. La devise associée à l’instrument de financement spécifié sera utilisée. Pour USD, 5,50 $ est représenté par 5500000. Lorsqu’il n’est pas fourni, la campagne dépensera de manière uniforme en fonction du budget total et de la durée de diffusion de la campagne. Disponible uniquement lorsque budget_optimization est défini sur LINE_ITEM pour la campagne parente Remarque : Cette valeur doit être inférieure ou égale au total_budget_amount_local_micro. Type : long Exemple : 5500000

Exemple de requête

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items/9cqi0?bid_amount_local_micro=140000

Exemple de réponse

    {
      "request": {
        "params": {
          "line_item_id": "9cqi0",
          "bid_amount_local_micro": 140000,
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "advertiser_user_id": "756201191646691328",
        "name": null,
        "placements": [
          "ALL_ON_TWITTER"
        ],
        "start_time": "2017-07-10T00:00:00Z",
        "bid_amount_local_micro": 140000,
        "advertiser_domain": null,
        "target_cpa_local_micro": null,
        "primary_web_event_tag": null,
        "goal": "ENGAGEMENT",
        "daily_budget_amount_local_micro": null,
        "product_type": "PROMOTED_TWEETS",
        "end_time": null,
        "bid_strategy": "MAX",
        "duration_in_days": null,
        "standard_delivery": null,
        "total_budget_amount_local_micro": null,
        "objective": "ENGAGEMENTS",
        "id": "9cqi0",
        "entity_status": "PAUSED",
        "automatic_tweet_promotion": null,
        "frequency_cap": null,
        "android_app_store_identifier": null,
        "categories": [],
        "currency": "USD",
        "pay_by": "ENGAGEMENT",
        "created_at": "2017-07-07T17:42:20Z",
        "ios_app_store_identifier": null,
        "updated_at": "2022-06-03T23:51:36Z",
        "campaign_id": "8yn7m",
        "creative_source": "MANUAL",
        "deleted": false
      }
    }

​

DELETE accounts/:account_id/line_items/:line_item_id

Supprime l’élément de ligne spécifié appartenant au compte actuel.

Remarque : La suppression d’un élément de ligne est irréversible et toute tentative ultérieure de supprimer la ressource renverra HTTP 404.

Remarque : Lorsqu’un élément de ligne est supprimé, ses enfants promoted_tweets ne sont renvoyés par les endpoints GET accounts/:account_id/promoted_tweets et GET accounts/:account_id/promoted_tweets/:promoted_tweet_id que si with_deleted=true est indiqué dans la requête. Ces promoted_tweets ne sont toutefois pas réellement supprimés ("deleted": false dans la réponse). Nous ne procédons pas à des suppressions en cascade.

Resource URL

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

Parameters

Name	Description
account_id required	L’identifiant du compte exploité. Apparaît dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: 18ce54d4x5t
line_item_id required	Référence de l’élément de ligne concerné par la requête. Type: string Example: 9f2ix

Example Request

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items/9f2ix

Example Response

    {
      "data": {
        "bid_strategy": "MAX",
        "advertiser_user_id": "756201191646691328",
        "name": "Sans titre",
        "placements": [],
        "start_time": null,
        "bid_amount_local_micro": 100000,
        "advertiser_domain": null,
        "target_cpa_local_micro": null,
        "primary_web_event_tag": null,
        "pay_by": "ENGAGEMENT",
        "product_type": "PROMOTED_TWEETS",
        "end_time": "2017-07-21T00:00:00Z",
        "duration_in_days": 1,
        "total_budget_amount_local_micro": null,
        "objective": "ENGAGEMENTS",
        "id": "9f2ix",
        "entity_status": "ACTIVE",
        "goal": "ENGAGEMENT",
        "frequency_cap": 5,
        "categories": [],
        "currency": "USD",
        "created_at": "2017-07-14T00:01:50Z",
        "updated_at": "2017-08-09T07:41:08Z",
        "campaign_id": "90r8n",
        "creative_source": "MANUAL",
        "deleted": true
      },
      "request": {
        "params": {
          "line_item_id": "9f2ix",
          "account_id": "18ce54d4x5t"
        }
      }
    }

​

Catégories sélectionnées de l’élément de ligne

Exécuter dans Postman

Des informations supplémentaires sur l’utilisation sont disponibles dans le Guide de l’objectif « Pré-roll Vues vidéo »

​

GET accounts/:account_id/line_item_curated_categories

Récupère les détails de certaines ou de l’ensemble des catégories sélectionnées d’éléments de campagne associées au compte actuel.

Resource URL

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

Parameters

Name	Description
account_id required	L’identifiant du compte exploité. Apparaît dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API des annonceurs, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: 18ce54d4x5t
count optional	Spécifie le nombre d’enregistrements à récupérer par requête distincte. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Spécifie un curseur pour obtenir la page suivante de résultats. Voir Pagination pour plus d’informations. Type: string Example: 8x7v00oow
sort_by optional	Trie selon un attribut pris en charge, par ordre croissant ou décroissant. Voir Sorting pour plus d’informations. Type: string Example: created_at-asc
with_deleted optional	Inclut les résultats supprimés dans votre requête. Type: boolean Default: false Possible values: true, false
with_total_count optional	Inclut l’attribut de réponse total_count. Note : Ce paramètre et cursor sont mutuellement exclusifs. Note : Les requêtes incluant total_count seront soumises à des limites de taux plus faibles, actuellement fixées à 200 par 15 minutes. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/abc1/line_item_curated_categories

Example Response

    {
      "request": {
        "params": {
          "account_id": "abc1"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "line_item_id": "by5pw",
          "curated_category_id": "7op29tp2jzeo",
          "id": "1",
          "created_at": "2018-06-29T04:19:53Z",
          "updated_at": "2018-06-29T04:19:53Z",
          "deleted": false
        }
      ]
    }

​

GET accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id

Récupère les détails d’une catégorie de ciblage d’élément de campagne spécifique associée au compte en cours.

URL de la ressource

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

Paramètres

Nom	Description
account_id obligatoire	L’identifiant du compte exploité. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
line_item_curated_category_id obligatoire	La référence de la catégorie de ciblage d’élément de campagne utilisée dans la requête. Type : string Exemple : 43853bhii885
with_deleted optionnel	Inclure les résultats supprimés dans la requête. Type : boolean Valeur par défaut : false Valeurs possibles : true, false

Exemple de requête

GET https://ads-api.x.com/12/accounts/abc1/line_item_curated_categories/yav

Exemple de réponse

    {
      "request": {
        "params": {
          "line_item_curated_category_id": "yav",
          "account_id": "abc1"
        }
      },
      "data": {
        "line_item_id": "by5pw",
        "curated_category_id": "7op29tp2jzeo",
        "id": "yav",
        "created_at": "2018-06-29T04:19:53Z",
        "updated_at": "2018-06-29T04:19:53Z",
        "deleted": false
      }
    }

​

POST accounts/:account_id/line_item_curated_categories

Associe un objet curated category à l’élément de ligne spécifié.

URL de la ressource

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

Paramètres

Nom	Description
account_id required	L’identifiant du compte exploité. Il apparaît dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Exemple : 18ce54d4x5t
curated_category_id required	Référence à l’entité curated category utilisée dans la requête. Type: string Exemple : 10miy
line_item_id required	Référence à l’élément de ligne utilisé dans la requête. Type: string Exemple : 8v7jo

Exemple de requête

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/line_item_curated_categories?line_item_id=iqwka&curated_category_id=9ddrgesiap6o

Exemple de réponse

    {
      "request": {
        "params": {
          "curated_category_id": "9ddrgesiap6o",
          "line_item_id": "iqwka",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "iqwka",
        "curated_category_id": "9ddrgesiap6o",
        "id": "xq",
        "created_at": "2021-03-30T17:26:42Z",
        "updated_at": "2021-03-30T17:26:42Z",
        "deleted": false
      }
    }

​

PUT accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id

Met à jour la catégorie sélectionnée de l’élément de ligne spécifié.

URL de la ressource

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

Paramètres

Nom	Description
account_id requis	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
line_item_curated_category_id requis	Référence à la catégorie sélectionnée de l’élément de ligne utilisée dans la requête. Type : string Exemple : 1bzq3
curated_category_id optional	Référence à l’entité de catégorie sélectionnée utilisée dans la requête. Type : string Exemple : 10miy
line_item_id optional	Référence à l’élément de ligne utilisée dans la requête. Type : string Exemple : 8v7jo

Exemple de requête

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/line_item_curated_categories/xq?curated_category_id=8tujl1p3yn0g

Exemple de réponse

    {
      "request": {
        "params": {
          "line_item_curated_category_id": "xq",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "iqwka",
        "curated_category_id": "8tujl1p3yn0g",
        "id": "xq",
        "created_at": "2021-03-30T17:26:42Z",
        "updated_at": "2021-03-30T18:22:52Z",
        "deleted": true
      }
    }

​

DELETE accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id

Supprime la catégorie organisée de l’élément de ligne spécifiée.

URL de ressource

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

Paramètres

Nom	Description
account_id requis	L’identifiant du compte exploité. Figure dans le chemin de la ressource et constitue généralement un paramètre obligatoire pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Exemple : 18ce54d4x5t
line_item_curated_category_id requis	Référence à la catégorie organisée de l’élément de ligne utilisée dans la requête. Type: string Exemple : 1bzq3

Exemple de requête

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/line_item_curated_categories/xq

Exemple de réponse

    {
      "request": {
        "params": {
          "line_item_curated_category_id": "xq",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "iqwka",
        "curated_category_id": "9ddrgesiap6o",
        "id": "xq",
        "created_at": "2021-03-30T17:26:42Z",
        "updated_at": "2021-03-30T18:22:52Z",
        "deleted": true
      }
    }

​

Emplacements d’articles de campagne

Exécuter dans Postman

​

GET line_items/placements

Récupère les combinaisons valides de placement et product_type.

URL de la ressource

https://ads-api.x.com/12/line_items/placements

Paramètres

Nom	Description
product_type facultatif	Restreint la réponse aux seuls emplacements valides pour le type de produit spécifié. Type : enum Valeurs possibles : MEDIA, PROMOTED_ACCOUNT, PROMOTED_TWEETS

Exemple de requête

GET https://ads-api.x.com/12/line_items/placements?product_type=PROMOTED_ACCOUNT

Exemple de réponse

    {
      "data": [
        {
          "product_type": "PROMOTED_ACCOUNT",
          "placements": [
            [
              "ALL_ON_TWITTER"
            ],
            [
              "TWITTER_TIMELINE"
            ]
          ]
        }
      ],
      "request": {
        "params": {
          "product_type": "PROMOTED_ACCOUNT"
        }
      }
    }

​

Créations média

Exécuter dans Postman

​

GET accounts/:account_id/media_creatives

Récupère les détails d’une partie ou de l’ensemble des créations média associées au compte actuel.

Resource URL

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

Parameters

Name	Description
account_id required	L’identifiant du compte exploité. Apparaît dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: 18ce54d4x5t
campaign_id optional	Restreint la réponse aux créations média associées à la campagne spécifiée. Type: string Example: 8gdx6
count optional	Spécifie le nombre d’enregistrements à récupérer par requête. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Spécifie un curseur pour obtenir la page suivante de résultats. Voir Pagination pour plus d’informations. Type: string Example: 8x7v00oow
line_item_ids optional	Restreint la réponse aux créations média associées aux line items spécifiés en fournissant une liste d’identifiants séparés par des virgules. Jusqu’à 200 ID peuvent être fournis. Type: string Example: 8v7jo
media_creative_ids optional	Restreint la réponse aux créations média souhaitées en fournissant une liste d’identifiants séparés par des virgules. Jusqu’à 200 ID peuvent être fournis. Type: string Example: 1bzq3
sort_by optional	Trie selon un attribut pris en charge, par ordre croissant ou décroissant. Voir Sorting pour plus d’informations. Type: string Example: created_at-asc
with_deleted optional	Inclure les résultats supprimés dans la réponse. Type: boolean Default: false Possible values: true, false
with_total_count optional	Inclure l’attribut de réponse total_count. Note : Ce paramètre et cursor sont exclusifs. Note : Les requêtes incluant total_count auront des limites de taux plus faibles, actuellement fixées à 200 par tranche de 15 minutes. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives?media_creative_ids=1bzq3

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "media_creative_ids": [
            "1bzq3"
          ]
        }
      },
      "next_cursor": null,
      "data": [
        {
          "line_item_id": "8v7jo",
          "landing_url": "https://dev.x.com",
          "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET",
          "id": "1bzq3",
          "entity_status": "ACTIVE",
          "created_at": "2017-07-05T06:00:42Z",
          "account_media_id": "10miy",
          "updated_at": "2019-01-11T20:21:26Z",
          "approval_status": "ACCEPTED",
          "deleted": false
        }
      ]
    }

​

GET accounts/:account_id/media_creatives/:media_creative_id

Récupère les détails d’un media creative spécifique associé au compte en cours.

Resource URL

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

Parameters

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

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives/1bzq3

Example Response

    {
      "request": {
        "params": {
          "media_creative_id": "1bzq3",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "8v7jo",
        "landing_url": "https://dev.x.com",
        "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET",
        "id": "1bzq3",
        "entity_status": "ACTIVE",
        "created_at": "2017-07-05T06:00:42Z",
        "account_media_id": "10miy",
        "updated_at": "2019-01-11T20:21:26Z",
        "approval_status": "ACCEPTED",
        "deleted": false
      }
    }

​

POST accounts/:account_id/media_creatives

Associer un objet account media à l’élément de ligne spécifié.

Utilisez cet endpoint pour promouvoir des publicités in-stream (lorsque le creative_type de l’account media est PREROLL) ou des publicités image (telles que BANNER ou INTERSTITIAL) sur la Twitter Audience Platform.

Remarque : Pour ajouter des ressources média à la ressource Account Media, utilisez l’endpoint POST accounts/:account_id/media_library.

Resource URL

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

Parameters

Name	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: 18ce54d4x5t
account_media_id required	Référence à l’entité account media utilisée dans la requête. Type: string Example: 10miy
line_item_id required	Référence à l’élément de ligne utilisé dans la requête. Type: string Example: 8v7jo
landing_url sometimes required	L’URL du site Web vers lequel diriger l’utilisateur. À utiliser uniquement avec les images TAP (ou « display creatives »). Cette valeur est ignorée avec des éléments preroll. Pour associer une URL à un élément preroll, utilisez l’endpoint POST accounts/:account_id/preroll_call_to_actions. Remarque : Requis lorsque l’objectif de l’élément de ligne est défini sur WEBSITE_CLICKS. Type: string Example: https://blog.x.com/

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives?line_item_id=8v7jo&account_media_id=10miy

Example Response

    {
      "request": {
        "params": {
          "line_item_id": "8v7jo",
          "account_media_id": "10miy",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "8v7jo",
        "landing_url": "https://dev.x.com",
        "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET",
        "id": "1bzq3",
        "entity_status": "ACTIVE",
        "created_at": "2017-07-05T06:00:42Z",
        "account_media_id": "10miy",
        "updated_at": "2019-01-11T20:21:26Z",
        "approval_status": "ACCEPTED",
        "deleted": false
      }
    }

​

DELETE accounts/:account_id/media_creatives/:media_creative_id

Supprime la création média spécifiée appartenant au compte actuel.

URL de la ressource

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

Paramètres

Nom	Description
account_id obligatoire	Identifiant du compte utilisé. Apparaît dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
media_creative_id obligatoire	Référence à la création média concernée par la requête. Type : string Exemple : 1bzq3

Exemple de requête

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives/1bzq3

Exemple de réponse

    {
      "request": {
        "params": {
          "media_creative_id": "1bzq3",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "8v7jo",
        "landing_url": "https://dev.x.com",
        "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET",
        "id": "1bzq3",
        "entity_status": "ACTIVE",
        "created_at": "2017-07-05T06:00:42Z",
        "account_media_id": "10miy",
        "updated_at": "2021-04-16T21:02:55Z",
        "approval_status": "ACCEPTED",
        "deleted": true
      }
    }

​

Comptes sponsorisés

Exécuter dans Postman

​

GET accounts/:account_id/promoted_accounts

Récupère les détails de certains ou de tous les comptes promus associés à un ou plusieurs éléments de campagne rattachés au compte actuel.

Utilisez GET users/lookup pour obtenir les données des utilisateurs correspondant aux comptes identifiés par user_id dans la réponse.

Un code HTTP 400 sera renvoyé si aucun des éléments de campagne spécifiés n’est configuré pour contenir des comptes promus.

Resource URL

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

Parameters

Name	Description
account_id required	L’identifiant du compte exploité. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: 18ce54d4x5t
count optional	Spécifie le nombre d’enregistrements à tenter de récupérer par requête distincte. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Spécifie un curseur pour obtenir la page suivante de résultats. Voir Pagination pour plus d’informations. Type: string Example: 8x7v00oow
line_item_ids optional	Limite la réponse aux seuls comptes promus associés aux éléments de campagne spécifiés en indiquant une liste d’identifiants séparés par des virgules. Jusqu’à 200 ID peuvent être fournis. Type: string Example: 9bpb2
promoted_account_ids optional	Limite la réponse aux seuls comptes promus souhaités en indiquant une liste d’identifiants séparés par des virgules. Jusqu’à 200 ID peuvent être fournis. Type: string Example: 19pl2
sort_by optional	Trie selon un attribut pris en charge, par ordre croissant ou décroissant. Voir Sorting pour plus d’informations. Type: string Example: created_at-asc
with_deleted optional	Inclure les résultats supprimés dans votre requête. Type: boolean Default: false Possible values: true, false
with_total_count optional	Inclure l’attribut de réponse total_count. Note: Ce paramètre et cursor sont mutuellement exclusifs. Note: Les requêtes incluant total_count auront des limites de taux plus faibles, actuellement fixées à 200 par 15 minutes. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts?promoted_account_ids=19pl2

Example Response

    {
      "request": {
        "params": {
          "promoted_account_ids": [
            "19pl2"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "line_item_id": "9bpb2",
          "user_id": "756201191646691328",
          "id": "19pl2",
          "entity_status": "ACTIVE",
          "created_at": "2017-07-05T05:54:13Z",
          "updated_at": "2017-07-05T05:54:13Z",
          "approval_status": "ACCEPTED",
          "deleted": false
        }
      ]
    }

​

GET accounts/:account_id/promoted_accounts/:promoted_account_id

Récupérer une référence spécifique à un compte associé à un élément de campagne dans le compte actuel.

Resource URL

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

Parameters

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

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts/19pl2

Example Response

    {
      "request": {
        "params": {
          "promoted_account_id": "19pl2",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "9bpb2",
        "user_id": "756201191646691328",
        "id": "19pl2",
        "entity_status": "ACTIVE",
        "created_at": "2017-07-05T05:54:13Z",
        "updated_at": "2017-07-05T05:54:13Z",
        "approval_status": "ACCEPTED",
        "deleted": false
      }
    }

​

POST accounts/:account_id/promoted_accounts

Associer un compte (user_id) à l’élément de campagne (line item) spécifié.

Si l’élément de campagne spécifié n’est pas configuré pour être associé aux Promoted Accounts, une erreur HTTP 400 INCOMPATIBLE_LINE_ITEM sera renvoyée. Si l’utilisateur spécifié n’est pas éligible à la promotion, une erreur HTTP 400 sera renvoyée et aucun utilisateur ne sera promu. Si l’utilisateur fourni est déjà promu, la requête sera ignorée.

Pour plus d’informations sur les Promoted Accounts, consultez notre page campaign management.

Remarque : Il n’est pas possible de mettre à jour (PUT) les entités de comptes promus.

Resource URL

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

Parameters

Name	Description
account_id required	L’identifiant du compte exploité. Apparaît dans le chemin de la ressource et constitue généralement un paramètre obligatoire pour toutes les requêtes de l’Advertiser API, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: 18ce54d4x5t
line_item_id required	Référence à l’élément de campagne (line item) concerné par la requête. Type: string Example: 9bpb2
user_id required	Référence à l’utilisateur concerné par la requête. Utilisez GET users/lookup pour récupérer un id d’utilisateur à partir d’un nom d’utilisateur (screen name). Type: long Example: 756201191646691328

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts?line_item_id=9bpb2&user_id=756201191646691328

Example Response

    {
      "data": {
        "line_item_id": "9bpb2",
        "user_id": "756201191646691328",
        "id": "19pl2",
        "entity_status": "ACTIVE",
        "created_at": "2017-07-05T05:54:13Z",
        "updated_at": "2017-07-05T05:54:13Z",
        "approval_status": "ACCEPTED",
        "deleted": false
      },
      "request": {
        "params": {
          "user_id": "756201191646691328",
          "line_item_id": "9bpb2",
          "account_id": "18ce54d4x5t"
        }
      }
    }

​

DELETE accounts/:account_id/promoted_accounts/:promoted_account_id

Dissocie un compte de l’élément de campagne spécifié.

URL de la ressource

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

Paramètres

Name	Description
account_id required	Identifiant du compte utilisé. Figure dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte indiqué doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
promoted_account_id required	Identifiant de l’instance de Compte promu associée à un élément de campagne. Type : string Exemple : 19pl2

Exemple de requête

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts/19pl2

Exemple de réponse

    {
      "data": {
        "line_item_id": "9bpb2",
        "user_id": "756201191646691328",
        "id": "19pl2",
        "entity_status": "ACTIVE",
        "created_at": "2017-07-05T05:54:13Z",
        "updated_at": "2017-08-23T18:53:15Z",
        "approval_status": "ACCEPTED",
        "deleted": true
      },
      "request": {
        "params": {
          "promoted_account_id": "19pl2",
          "account_id": "18ce54d4x5t"
        }
      }
    }

​

Tweets sponsorisés

Exécuter dans Postman

​

GET accounts/:account_id/promoted_tweets

Récupère des références aux Tweets associés aux éléments de ligne du compte actuel.

Utilisez l’endpoint GET accounts/:account_id/tweets pour récupérer les objets Tweet. Utilisez les valeurs tweet_id pour chaque objet promoted_tweets.

Remarque : Lorsque les éléments de ligne parents sont supprimés, les promoted_tweets ne sont renvoyés que si with_deleted=true est indiqué dans la requête. Toutefois, ces promoted_tweets ne sont pas réellement supprimés ("deleted": false dans la réponse).

Resource URL

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

Parameters

Name	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Exemple : 18ce54d4x5t
count optional	Spécifie le nombre d’enregistrements à récupérer par requête. Type: int Par défaut : 200 Min, Max : 1, 1000
cursor optional	Spécifie un curseur pour obtenir la page suivante de résultats. Voir Pagination pour plus d’informations. Type: string Exemple : 8x7v00oow
line_item_ids optional	Limite la réponse aux Tweets associés à des éléments de ligne spécifiques en indiquant une liste d’identifiants séparés par des virgules. Jusqu’à 200 ID peuvent être fournis. Type: string Exemple : 96uzp
promoted_tweet_ids optional	Limite la réponse aux Tweets promus souhaités en indiquant une liste d’identifiants séparés par des virgules. Jusqu’à 200 ID peuvent être fournis. Type: string Exemple : 1efwlo
sort_by optional	Trie selon un attribut pris en charge, par ordre croissant ou décroissant. Voir Sorting pour plus d’informations. Type: string Exemple : created_at-asc
with_deleted optional	Inclure les résultats supprimés dans la requête. Type: boolean Par défaut : false Valeurs possibles : true, false
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 15 minutes. Type: boolean Par défaut : false Valeurs possibles : true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets?promoted_tweet_ids=1efwlo

Example Response

    {
      "request": {
        "params": {
          "promoted_tweet_ids": [
            "1efwlo"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "line_item_id": "96uzp",
          "id": "1efwlo",
          "entity_status": "ACTIVE",
          "created_at": "2017-06-29T05:06:57Z",
          "updated_at": "2017-06-29T05:08:46Z",
          "approval_status": "ACCEPTED",
          "tweet_id": "880290790664060928",
          "deleted": false
        }
      ]
    }

​

GET accounts/:account_id/promoted_tweets/:promoted_tweet_id

Récupère une référence spécifique à un Tweet associé à un élément de ligne du compte actuel.

Remarque : Lorsque les éléments de ligne parents sont supprimés, les promoted_tweets ne sont renvoyés que si with_deleted=true est spécifié dans la requête. Ces promoted_tweets ne sont toutefois pas réellement supprimés ("deleted": false dans la réponse).

Resource URL

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

Parameters

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

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets/1efwlo

Example Response

    {
      "request": {
        "params": {
          "promoted_tweet_id": "1efwlo",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "96uzp",
        "id": "1efwlo",
        "entity_status": "ACTIVE",
        "created_at": "2017-06-29T05:06:57Z",
        "updated_at": "2017-06-29T05:08:46Z",
        "approval_status": "ACCEPTED",
        "tweet_id": "880290790664060928",
        "deleted": false
      }
    }

​

POST accounts/:account_id/promoted_tweets

Associe un ou plusieurs Tweets à la ligne d’achat spécifiée. Tous les Tweets ne se prêtent pas à la promotion, selon l’objectif de campagne. Consultez Objective-based Campaigns pour en savoir plus.

Lorsque vous utilisez le type de produit PROMOTED_ACCOUNT, associer un Tweet au line_item ajoutera des emplacements dans le fil sur mobile en plus de l’emplacement standard PROMOTED_ACCOUNT.

Remarque : il n’est pas possible de mettre à jour (PUT) des entités de Tweet promu.

Resource URL

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

Parameters

Name	Description
account_id required	L’identifiant du compte exploité. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: 18ce54d4x5t
line_item_id required	Référence à la ligne d’achat ciblée par la requête. Type: string Example: 8v7jo
tweet_ids required	Liste d’identifiants, séparés par des virgules, correspondant à des Tweets spécifiques. Jusqu’à 50 identifiants peuvent être fournis. Type: long Example: 822333526255120384

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets?line_item_id=8v7jo&tweet_ids=822333526255120384

Example Response

    {
      "data": [
        {
          "line_item_id": "8v7jo",
          "id": "1e8i2k",
          "entity_status": "ACTIVE",
          "created_at": "2017-06-24T04:21:36Z",
          "updated_at": "2017-06-24T04:21:36Z",
          "approval_status": "ACCEPTED",
          "tweet_id": "822333526255120384",
          "deleted": false
        }
      ],
      "request": {
        "params": {
          "line_item_id": "8v7jo",
          "tweet_ids": [
            822333526255120384
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "total_count": 1
    }

​

DELETE accounts/:account_id/promoted_tweets/:promoted_tweet_id

Dissocie un Tweet de l’élément de campagne spécifié.

Remarque : Une entité promoted_tweets supprimée s’affichera comme « Paused » dans l’interface ads.x.com. De même, l’action « pausing » depuis l’interface dissociera le Tweet de son élément de campagne.

Resource URL

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

Parameters

Name	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: 18ce54d4x5t
promoted_tweet_id required	L’identifiant de l’instance d’un Promoted Tweet associée à un élément de campagne. Il provient du champ id d’un élément de réponse à GET accounts/:account_id/promoted_tweets, et non du tweet_id du Tweet concerné. Fourni dans le chemin de la ressource. Type: string Example: 1gp8a5

Example Request

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets/1gp8a5

Example Response

    {
      "data": {
        "line_item_id": "9pl99",
        "id": "1gp8a5",
        "entity_status": "ACTIVE",
        "created_at": "2017-08-17T17:02:21Z",
        "updated_at": "2017-08-18T06:43:48Z",
        "approval_status": "ACCEPTED",
        "tweet_id": "844796297743757315",
        "deleted": true
      },
      "request": {
        "params": {
          "promoted_tweet_id": "1gp8a5",
          "account_id": "18ce54d4x5t"
        }
      }
    }

​

Utilisateurs éligibles à la promotion

Exécuter dans Postman

​

GET accounts/:account_id/promotable_users

Récupérer les détails pour certains ou l’ensemble des utilisateurs promouvables associés au compte en cours.

Le type d’utilisateur promouvable est soit FULL, soit RETWEETS_ONLY. Cela détermine le type de contenu que le compte est autorisé à promouvoir. Les annonceurs doivent obtenir l’autorisation de promouvoir le contenu d’un autre utilisateur et contacter X pour les ajouter à votre compte en tant qu’utilisateur promouvable RETWEETS_ONLY.

À condition que les autorisations soient correctement configurées, vous pouvez effectuer des requêtes vers les endpoints de produits promus qui référencent directement l’ID du Tweet que vous souhaitez promouvoir. Vous pouvez utiliser l’endpoint POST accounts/:account_id/promoted-tweets pour promouvoir des Tweets publiés et l’endpoint POST accounts/:account_id/scheduled-promoted-tweets pour promouvoir les Tweets programmés d’un autre compte X Ads.

Vous n’avez pas besoin de Retweeter le Tweet cible. Lorsque vous promouvez un Tweet avec cette approche, le tweet_id renvoyé sera différent de l’ID du Tweet fourni. En arrière-plan, le Tweet est retweeté en tant que Tweet nullcasté, puis promu. Le tweet_id renvoyé correspond à ce nouveau Tweet.

Resource URL

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

Parameters

Name	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: 18ce54d4x5t
count optional	Spécifie le nombre d’enregistrements à tenter de récupérer par requête. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Spécifie un curseur pour obtenir la page suivante de résultats. Voir Pagination pour plus d’informations. Type: string Example: 8x7v00oow
promotable_user_ids optional	Limite la réponse aux seuls utilisateurs promouvables souhaités en spécifiant une liste d’identifiants séparés par des virgules. Jusqu’à 200 id peuvent être fournis. Type: string Example: l310s
sort_by optional	Trie selon un attribut pris en charge, par ordre croissant ou décroissant. Voir Sorting pour plus d’informations. Type: string Example: created_at-asc
with_deleted optional	Inclut les résultats supprimés dans votre requête. Type: boolean Default: false Possible values: 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 basses, actuellement fixées à 200 par 15 minutes. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promotable_users?promotable_user_ids=l310s

Example Response

    {
      "request": {
        "params": {
          "promotable_user_ids": [
            "l310s"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "user_id": "756201191646691328",
          "id": "l310s",
          "created_at": "2016-07-21T22:42:09Z",
          "updated_at": "2016-07-21T22:42:09Z",
          "deleted": false,
          "promotable_user_type": "FULL"
        }
      ]
    }

​

GET accounts/:account_id/promotable_users/:promotable_user_id

Récupère un utilisateur promouvable spécifique associé au compte actuel.

Le type d’utilisateur promouvable est soit FULL, soit RETWEETS_ONLY. Cela détermine le type de contenu que le compte est autorisé à promouvoir.

Les annonceurs doivent obtenir l’autorisation de promouvoir le contenu d’un autre utilisateur. Si les autorisations sont correctement configurées, vous pouvez envoyer des requêtes aux endpoints de produits promus qui font directement référence à l’ID du Tweet que vous souhaitez promouvoir.

Vous n’avez pas besoin de retweeter le Tweet cible. Lorsque vous promouvez un Tweet de cette manière, le tweet_id renvoyé sera différent de l’ID du Tweet fourni. En arrière-plan, le Tweet est retweeté en tant que Tweet diffusé en nullcast, puis promu. Le tweet_id renvoyé correspond à ce nouveau Tweet.

URL de la ressource

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

Paramètres

Nom	Description
account_id requis	Identifiant du compte utilisé. Apparaît dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Exemple: 18ce54d4x5t
promotable_user_id optionnel	Référence à l’utilisateur promouvable ciblé par la requête. Type: string Exemple: l310s
with_deleted optionnel	Inclure les résultats supprimés dans la réponse. Type: boolean Valeur par défaut : false Valeurs possibles : true, false

Exemple de requête

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promotable_users/l310s

Exemple de réponse

    {
      "request": {
        "params": {
          "promotable_user_id": "l310s",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "user_id": "2417045708",
        "id": "l310s",
        "created_at": "2017-03-10T17:51:24Z",
        "updated_at": "2017-03-10T17:51:24Z",
        "deleted": false,
        "promotable_user_type": "RETWEETS_ONLY"
      }
    }

​

Éditeurs

Exécuter dans Postman

​

GET publishers

Récupère la liste des informations des éditeurs de catégorie de contenu

Des informations supplémentaires sont disponibles dans le Guide de l’objectif Video Views Preroll

URL de la ressource

https://ads-api.x.com/12/publishers

Paramètres

Aucun paramètre de requête

Exemple de requête

GET https://ads-api.x.com/12/publishers

Exemple de réponse

{
      "request": {
        "params": {}
      },
      "next_cursor": null,
      "data": [
        {
          "monetizable_country_codes": [
            "US"
          ],
          "promotion_eligible_country_codes": [
            "US"
          ],
          "username": "PeoplesSports",
          "user_id": "1353868435021721602",
          "monetization_restricted": true,
          "content_category_ids": [
            "se"
          ]
        },
        {
          "monetizable_country_codes": [
            "JP"
          ],
          "promotion_eligible_country_codes": [
            "JP"
          ],
          "username": "NewYork_Jack",
          "user_id": "1331177123436851206",
          "monetization_restricted": true,
          "content_category_ids": [
            "sk"
          ]
        },
        {
          "monetizable_country_codes": [
            "JP"
          ],
          "promotion_eligible_country_codes": [
            "JP"
          ],
          "username": "twispatv",
          "user_id": "1331165719128461314",
          "monetization_restricted": true,
          "content_category_ids": [
            "sm"
          ]
        },
        {
          "monetizable_country_codes": [
            "US"
          ],
          "promotion_eligible_country_codes": [
            "US"
          ],
          "username": "LAThieves",
          "user_id": "1316808678897455105",
          "monetization_restricted": true,
          "content_category_ids": [
            "s0"
          ]
        },
        {
          "monetizable_country_codes": [
            "US"
          ],
          "promotion_eligible_country_codes": [
            "US"
          ],
          "username": "Quicktake_EE",
          "user_id": "1305900477427724290",
          "monetization_restricted": true,
          "content_category_ids": [
            "sr"
          ]
        },
        {
          "monetizable_country_codes": [
            "BR"
          ],
          "promotion_eligible_country_codes": [
            "BR"
          ],
          "username": "eufloribella",
          "user_id": "1300812459054436354",
          "monetization_restricted": true,
          "content_category_ids": [
            "sm"
          ]
        },
        {
          "monetizable_country_codes": [
            "EG"
          ],
          "promotion_eligible_country_codes": [
            "KW",
            "EG",
            "SA",
            "AE",
            "LB",
            "QA"
          ],
          "username": "Egypt2021EN",
          "user_id": "1296077573399678977",
          "monetization_restricted": true,
          "content_category_ids": [
            "se"
          ]
        },
        {
          "monetizable_country_codes": [
            "US"
          ],
          "promotion_eligible_country_codes": [
            "US"
          ],
          "username": "ClubShayShay",
          "user_id": "1283068366706454529",
          "monetization_restricted": true,
          "content_category_ids": [
            "se"
          ]
        },
        {
          "monetizable_country_codes": [
            "IN",
            "KW",
            "ID",
            "EG",
            "SG",
            "TH",
            "MY",
            "PH",
            "ES",
            "US",
            "AU",
            "SA",
            "AE",
            "LB",
            "GB",
            "FR",
            "KR",
            "BR",
            "MX",
            "QA",
            "CA",
            "JP"
          ],
          "promotion_eligible_country_codes": [
            "KW",
            "EG",
            "SA",
            "AE",
            "LB",
            "QA"
          ],
          "username": "hiaahsanshow",
          "user_id": "1253421442143641601",
          "monetization_restricted": false,
          "content_category_ids": [
            "sh"
          ]
        },
        {
          "monetizable_country_codes": [
            "TH"
          ],
          "promotion_eligible_country_codes": [
            "TH"
          ],
          "username": "HoneKrasae",
          "user_id": "1240684293719904256",
          "monetization_restricted": true,
          "content_category_ids": [
            "sr"
          ]
        },
        {
          "monetizable_country_codes": [
            "US"
          ],
          "promotion_eligible_country_codes": [
            "US"
          ],
          "username": "Sportskind",
          "user_id": "1232708694418300930",
          "monetization_restricted": true,
          "content_category_ids": [
            "se"
          ]
        },
        {
          "monetizable_country_codes": [
            "IN",
            "KW",
            "ID",
            "EG",
            "SG",
            "TH",
            "MY",
            "PH",
            "ES",
            "US",
            "AU",
            "SA",
            "AE",
            "LB",
            "GB",
            "FR",
            "KR",
            "BR",
            "MX",
            "QA",
            "CA",
            "JP"
          ],
          "promotion_eligible_country_codes": [
            "KW",
            "EG",
            "SA",
            "AE",
            "LB",
            "QA"
          ],
          "username": "almeerathShow",
          "user_id": "1229410512762437633",
          "monetization_restricted": false,
          "content_category_ids": [
            "sh"
          ]
        },
        {
          "monetizable_country_codes": [
            "US"
          ],
          "promotion_eligible_country_codes": [
            "US"
          ],
          "username": "SeeYourVoiceFOX",
          "user_id": "1225490734653947904",
          "monetization_restricted": true,
          "content_category_ids": [
            "sh"
          ]
        },
        {
          "monetizable_country_codes": [
            "IN",
            "KW",
            "ID",
            "EG",
            "SG",
            "TH",
            "MY",
            "PH",
            "ES",
            "US",
            "AU",
            "SA",
            "AE",
            "LB",
            "GB",
            "FR",
            "KR",
            "BR",
            "MX",
            "QA",
            "CA",
            "JP"
          ],
          "promotion_eligible_country_codes": [
            "US"
          ],
          "username": "AUProSports",
          "user_id": "1219303449768185859",
          "monetization_restricted": false,
          "content_category_ids": [
            "se"
          ]
        }
      ]
    }

​

Recommandations

Exécuter dans Postman

​

GET accounts/:account_id/recommendations

Statut : bêta fermée

Récupère les recommandations de campagne associées à ce compte publicitaire. Actuellement, la limite est d’une recommandation par instrument de financement.

Resource URL

https://ads-api.x.com/5/accounts/:account_id/recommendations

Parameters

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

Example Request

GET https://ads-api.x.com/5/accounts/18ce54d4x5t/recommendations

Example Response

    "request": {
      "params": {
        "account_id": "18ce54d4x5t"
      }
    },
    "total_count": 1,
    "data": [
      {
        "funding_instrument_id": "gpvzb",
        "id": "62ce8zza1q0w",
        "account_id": "18ce54d4x5t",
        "status": "EN ATTENTE",
        "message": "Recommandation pour des tests"
        "created_at": "2016-11-14T23:07:54Z",
        "updated_at": "2016-11-14T23:07:54Z"
      }
    ]

​

GET accounts/:account_id/recommendations/:recommendation_id

Statut : bêta fermée

Récupérer une recommandation de campagne spécifique associée à ce compte publicitaire.

La recommandation de campagne contient un ensemble complet de modifications proposées pour la structure de la campagne, représentée sous forme d’arborescence d’objets. L’arborescence de réponse est conçue pour fonctionner avec les endpoints de l’API Batch, mais elle peut également être associée à des endpoints de mise à jour unitaires selon le cas (Create pour POST, Update pour PUT, Delete pour DELETE).

Resource URL

https://ads-api.x.com/5/accounts/:account_id/recommendations/:recommendation_id

Parameters

Nom	Description
account_id obligatoire	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre obligatoire pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte indiqué doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
recommendation_id obligatoire	La référence à l’id de recommandation concernée par la requête Type : string Exemple : 62ce8zza1q0w

Example Request

GET https://ads-api.x.com/5/accounts/18ce54d4x5t/recommendations/62ce8zza1q0w

Example Response

{
    "request": {
      "params": {
        "recommendation_id": "62ce8zza1q0w",
        "account_id": "18ce54d4x5t"
      }
    },
    "data_type": "recommendations",
      "data": {
      "changes": [
        {
          "entity_type": "campaigns",
          "params": {
            "start_time": "2016-11-08T22:00:00Z",
            "daily_budget_amount_local_micro": 2200000,
            "end_time": "2016-11-16T07:59:00Z",
            "total_budget_amount_local_micro": 12000000,
            "id": "64m0d"
          },
          "operation_type": "Mise à jour",
          "dependent_entities": [
            {
              "entity_type": "line_items",
              "params": {
                "name": "Campagne pour des recommandations",
                "placements": [
                  "TWITTER_TIMELINE"
                ],
                "bid_amount_local_micro": 1430000,
                "id": "6f5kq",
                "include_sentiment": "ALL",
              },
              "operation_type": "Mise à jour",
              "dependent_entities": [
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "id": "a8po6p"
                  },
                  "operation_type": null,
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "election results",
                    "targeting_value": "election results",
                    "targeting_type": "PHRASE_KEYWORD"
                  },
                  "operation_type": "Création",
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "id": "101ftp"
                  },
                  "operation_type": "Suppression",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "Male",
                    "targeting_value": 1,
                    "targeting_type": "GENDER"
                  },
                  "operation_type": "Création",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "San Francisco–Oakland–San Jose CA, US",
                    "targeting_value": "",
                    "targeting_type": "LOCATION"
                  },
                  "operation_type": "Création",
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "id": "101fto"
                  },
                  "operation_type": "Suppression",
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "line_item_id": "6f5kq",
                    "display_properties": [],
                    "paused": false,
                    "approval_status": "ACCEPTED",
                    "tweet_id": "91125952589766656"
                  },
                  "operation_type": "Création",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "Ciblage d’audience partenaire",
                    "targeting_value": "v2cx",
                    "targeting_type": "NEGATIVE_BEHAVIOR"
                  },
                  "operation_type": "Création",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "AGE_21_TO_34",
                    "targeting_value": "AGE_21_TO_34",
                    "targeting_type": "AGE"
                  },
                  "operation_type": "Création",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "id": "a8po6o"
                  },
                  "operation_type": "Suppression",
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "line_item_id": "6f5kq",
                    "display_properties": [],
                    "paused": false,
                    "approval_status": "ACCEPTED",
                    "tweet_id": "991101965843460096"
                  },
                  "operation_type": "Création",
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "line_item_id": "6f5kq",
                    "display_properties": [],
                    "paused": false,
                    "approval_status": "ACCEPTED",
                    "tweet_id": "991127212156096516"
                  },
                  "operation_type": "Création",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "debate",
                    "targeting_value": "debate",
                    "targeting_type": "NEGATIVE_PHRASE_KEYWORD"
                  },
                  "operation_type": "Création",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "60004, IL, US",
                    "targeting_value": "",
                    "targeting_type": "LOCATION"
                  },
                  "operation_type": "Create",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "id": "a8po6n"
                  },
                  "operation_type": null,
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "id": "101ftn"
                  },
                  "operation_type": null,
                  "dependent_entities": []
                }
              ]
            }
          ]
        }
      ],
      "funding_instrument_id": "gpvzb",
      "id": "62ce8zza1q0w",
      "account_id": "18ce54d4x5t",
      "status": "EN ATTENTE",
      "message": "Recommandation pour test"
      "created_at": "2016-11-14T23:07:54Z",
      "updated_at": "2016-11-14T23:07:54Z"
      }
    }

​

Tweets sponsorisés programmés

Exécuter dans Postman

​

GET accounts/:account_id/scheduled_promoted_tweets

Récupère les détails de certains ou de l’ensemble des Tweets promus planifiés associés au compte actuel.

Resource URL

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

Parameters

Name	Description
account_id required	L’identifiant du compte utilisé. Il apparaît dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: 18ce54d4x5t
count optional	Indique le nombre d’enregistrements à tenter de récupérer par requête distincte. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Indique un curseur pour obtenir la page suivante de résultats. Voir Pagination pour plus d’informations. Type: string Example: 8x7v00oow
line_item_ids optional	Limite la réponse aux seuls Tweets planifiés associés à des éléments de campagne spécifiques en fournissant une liste d’identifiants séparés par des virgules. Jusqu’à 200 id peuvent être fournis. Type: string Example: 8xdpe
scheduled_promoted_tweet_ids optional	Limite la réponse aux seuls Tweets promus planifiés souhaités en fournissant une liste d’identifiants séparés par des virgules. Jusqu’à 200 id peuvent être fournis. Type: string Example: 1xboq
sort_by optional	Trie selon un attribut pris en charge, par ordre croissant ou décroissant. Voir Sorting pour plus d’informations. Type: string Example: created_at-asc
with_deleted optional	Inclut les résultats supprimés dans la réponse. Type: boolean Default: false Possible values: true, false
with_total_count optional	Inclut l’attribut de réponse total_count. Note: Ce paramètre et cursor sont mutuellement exclusifs. Note: Les requêtes incluant total_count sont soumises à des limites de taux plus faibles, actuellement fixées à 200 par tranche de 15 minutes. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets?scheduled_promoted_tweet_ids=1xboq

Example Response

    {
      "request": {
        "params": {
          "scheduled_promoted_tweet_ids": [
            "1xboq"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "line_item_id": "8xdpe",
          "id": "1xboq",
          "created_at": "2017-06-01T19:53:32Z",
          "updated_at": "2017-06-01T20:00:06Z",
          "scheduled_tweet_id": "870366669373194240",
          "tweet_id": "870369382207070208",
          "deleted": false
        }
      ]
    }

​

GET accounts/:account_id/scheduled_promoted_tweets/:scheduled_promoted_tweet_id

Récupérer un Tweet promu planifié spécifique associé au compte actuel.

URL de ressource

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

Paramètres

Nom	Description
account_id obligatoire	Identifiant du compte utilisé. Figure dans le chemin de la ressource et constitue généralement un paramètre obligatoire pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
scheduled_promoted_tweet_id obligatoire	Référence au Tweet promu planifié ciblé par la requête. Type : string Exemple : 1xboq
with_deleted optionnel	Inclure les résultats supprimés dans la réponse. Type : boolean Valeur par défaut : false Valeurs possibles : true, false

Exemple de requête

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets/1xboq

Exemple de réponse

    {
      "request": {
        "params": {
          "scheduled_promoted_tweet_id": "1xboq",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "8xdpe",
        "id": "1xboq",
        "created_at": "2017-06-01T19:53:32Z",
        "updated_at": "2017-06-01T20:00:06Z",
        "scheduled_tweet_id": "870366669373194240",
        "tweet_id": "870369382207070208",
        "deleted": false
      }
    }

​

POST accounts/:account_id/scheduled_promoted_tweets

Associer un Tweet planifié à l’élément de ligne spécifié.

Remarque : il n’est pas possible de mettre à jour (PUT) des entités de Tweet promu planifié.

Resource URL

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

Parameters

Name	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: 18ce54d4x5t
line_item_id required	Référence à l’élément de ligne concerné par la requête. Type: string Example: 8xdpe
scheduled_tweet_id required	Référence au Tweet planifié concerné par la requête. Type: long Example: 870358555227860992

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets?line_item_id=8xdpe&scheduled_tweet_id=870358555227860992

Example Response

    {
      "data": {
        "line_item_id": "8xdpe",
        "id": "1xtfl",
        "created_at": "2017-06-08T07:25:26Z",
        "updated_at": "2017-06-08T07:25:26Z",
        "scheduled_tweet_id": "870358555227860992",
        "tweet_id": null,
        "deleted": false
      },
      "request": {
        "params": {
          "line_item_id": "8xdpe",
          "scheduled_tweet_id": 870358555227860992,
          "account_id": "18ce54d4x5t"
        }
      }
    }

​

DELETE accounts/:account_id/scheduled_promoted_tweets/:scheduled_promoted_tweet_id

Dissocier un Tweet programmé de la ligne d’article spécifiée.

Remarque : scheduled_promoted_tweets ne peut être supprimé qu’avant l’heure scheduled_at du Tweet programmé.

Resource URL

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

Parameters

Name	Description
account_id required	L’identifiant du compte exploité. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: 18ce54d4x5t
scheduled_promoted_tweet_id required	Une référence au Tweet promu programmé concerné par la requête. Il s’agit de l’attribut id d’un objet de réponse GET accounts/:account_id/scheduled_promoted_tweets. Type: string Example: 1xtfl

Example Request

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets/1xtfl

Example Response

    {
      "data": {
        "line_item_id": "8xdpe",
        "id": "1xtfl",
        "created_at": "2017-06-08T07:25:26Z",
        "updated_at": "2017-06-15T05:14:12Z",
        "scheduled_tweet_id": "870358555227860992",
        "tweet_id": null,
        "deleted": true
      },
      "request": {
        "params": {
          "scheduled_promoted_tweet_id": "1xtfl",
          "account_id": "18ce54d4x5t"
        }
      }
    }

​

Critères de ciblage

Exécuter dans Postman

​

GET accounts/:account_id/targeting_criteria

Récupère les détails de certains ou de l’ensemble des critères de ciblage associés aux éléments de campagne du compte actuel.

Resource URL

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

Parameters

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. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: 18ce54d4x5t
line_item_ids required	Limite la réponse aux seuls critères de ciblage des éléments de campagne spécifiés, en fournissant une liste d’identifiants séparés par des virgules. Jusqu’à 200 IDs peuvent être fournis. Type: string Example: 8u94t
count optional	Spécifie le nombre d’enregistrements à récupérer par requête distincte. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Spécifie un curseur pour obtenir la page suivante de résultats. Voir Pagination pour plus d’informations. Type: string Example: 8x7v00oow
lang optional	Code de langue ISO-639-1. Lorsqu’il est fourni, un attribut supplémentaire localized_name est renvoyé dans la réponse pour les objets disposant d’un nom localisé. Type: string Example: fr
sort_by optional	Trie selon un attribut pris en charge, par ordre croissant ou décroissant. Voir Sorting pour plus d’informations. Type: string Example: created_at-asc
targeting_criterion_ids optional	Limite la réponse aux critères de ciblage souhaités en fournissant une liste d’identifiants séparés par des virgules. Jusqu’à 200 IDs peuvent être fournis. Type: string Example: dpl3a6
with_deleted optional	Inclure les résultats supprimés dans la requête. Type: boolean Default: false Possible values: true, false
with_total_count optional	Inclure l’attribut de réponse total_count. Remarque : Ce paramètre et cursor sont mutuellement exclusifs. Remarque : Les requêtes incluant total_count sont soumises à des limites de taux plus faibles, actuellement fixées à 200 par tranche de 15 minutes. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria?line_item_ids=8u94t

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "line_item_ids": [
            "8u94t"
          ]
        }
      },
      "next_cursor": null,
      "data": [
        {
          "line_item_id": "8u94t",
          "name": "Ciblage d’audiences personnalisées",
          "id": "dpl3a6",
          "operator_type": "EQ",
          "created_at": "2017-05-26T03:29:35Z",
          "targeting_value": "249yj",
          "updated_at": "2017-05-26T03:29:35Z",
          "deleted": false,
          "targeting_type": "CUSTOM_AUDIENCE"
        }
      ]
    }

​

GET accounts/:account_id/targeting_criteria/:targeting_criterion_id

Récupère un critère de ciblage spécifique associé au compte en cours.

Resource URL

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

Parameters

Name	Description
account_id required	L’identifiant du compte utilisé. Figure dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: 18ce54d4x5t
targeting_criterion_id required	La référence du critère de ciblage concerné par la requête. Type: string Example: eijd4y
lang optional	Code de langue ISO-639-1. S’il est fourni, un attribut supplémentaire localized_name sera renvoyé dans la réponse pour les objets disposant d’un nom localisé. Type: string Example: fr
with_deleted optional	Inclure les résultats supprimés dans la requête. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria/eijd4y

Example Response

    {
      "request": {
        "params": {
          "targeting_criterion_id": "eijd4y",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "619jl",
        "name": "🤖",
        "id": "eijd4y",
        "created_at": "2017-07-06T16:51:04Z",
        "targeting_value": "🤖",
        "updated_at": "2017-07-06T16:51:04Z",
        "deleted": false,
        "targeting_type": "BROAD_KEYWORD"
      }
    }

​

POST accounts/:account_id/targeting_criteria

Consultez la page Targeting Options pour trouver les targeting_value correspondant à des types de ciblage spécifiques. Nous recommandons d’actualiser toutes les données chaque semaine afin de vous assurer de travailler avec l’ensemble le plus récent de valeurs de types de ciblage. Nous modifions les valeurs et les critères de ciblage disponibles de temps à autre ; bien que la majorité ne change pas souvent, certains évoluent. Il n’y a aucune garantie que ces valeurs ne changeront pas.

Utilisez les types de ciblage BROAD_KEYWORD, EXACT_KEYWORD, PHRASE_KEYWORD ou UNORDERED_KEYWORD avec les mots-clés spécifiés dans le targeting_value. Excluez des mots-clés en utilisant le paramètre de requête operator_type défini sur NE. Voir targeting keyword types pour une description détaillée de chaque type.

Note : Il n’est possible de cibler qu’un seul segment d’âge par élément de ligne.

Note : Pour cibler une Custom Audience, cette audience doit être ciblable, c.-à-d. targetable doit être égal à true.

Note : Lors de l’utilisation du type de ciblage TV_SHOW, il doit y avoir au moins un critère de ciblage LOCATION sur l’élément de ligne avant de définir le ciblage TV_SHOW, et toutes les LOCATION doivent être dans la même locale que le TV_SHOW visé.

Resource URL

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

Parameters

Name	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API des annonceurs, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Exemple : 18ce54d4x5t
line_item_id required	Une référence à l’élément de ligne sur lequel porte la requête. Type: string Exemple : 69ob
operator_type required	Spécifie la relation que doit avoir le critère de ciblage. Par exemple, pour exclure des mots-clés, utilisez operator_type=NE. Type: enum Valeurs possibles : EQ, NE, GTE, LT
targeting_type required	Le type de ciblage qui sera appliqué à cet élément de ligne. Les valeurs possibles non basées sur des mots-clés incluent : AGE, DEVICE, EVENT, CAMPAIGN_ENGAGEMENT, CAMPAIGN_ENGAGEMENT_LOOKALIKE, CONVERSATION, ENGAGEMENT_TYPE, FOLLOWERS_OF_USER, GENDER, INTEREST, LANGUAGE, LIVE_TV_EVENT, LOCATION, NETWORK_ACTIVATION_DURATION, NETWORK_OPERATOR, PLATFORM, PLATFORM_VERSION, SIMILAR_TO_FOLLOWERS_OF_USER, TV_SHOW, USER_ENGAGEMENT, USER_ENGAGEMENT_LOOKALIKE, WIFI_ONLY Note : Il n’est possible de cibler qu’un seul segment AGE par élément de ligne. Les valeurs possibles basées sur des mots-clés incluent : BROAD_KEYWORD, EXACT_KEYWORD, PHRASE_KEYWORD, UNORDERED_KEYWORD Les valeurs possibles pour les audiences personnalisées incluent : CUSTOM_AUDIENCE, CUSTOM_AUDIENCE_EXPANDED Valeurs possibles de catégorie de boutique d’apps installées : APP_STORE_CATEGORY, APP_STORE_CATEGORY_LOOKALIKE Exclusion possible d’app de Twitter Audience Platform (TAP) : APP_LIST (ne peut être utilisée qu’avec operator_type=NE)
targeting_value required	Indique quel utilisateur, quel centre d’intérêt, quel emplacement, quel événement, quelle plateforme, quelle version de plateforme, quel appareil, quel mot-clé ou quelle expression, quel genre, quelle audience personnalisée, quelle catégorie de boutique d’apps ou quelle exclusion d’une liste d’apps ce ciblage concernera, selon le targeting_type sélectionné. Type: string Exemple : 174958347

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria?line_item_id=619jl&targeting_type=BROAD_KEYWORD&targeting_value=technology

Exemple de réponse

    {
      "data": {
        "line_item_id": "619jl",
        "name": "technology",
        "id": "fbyjlr",
        "created_at": "2017-09-06T07:31:21Z",
        "targeting_value": "technology",
        "updated_at": "2017-09-06T07:31:21Z",
        "deleted": false,
        "targeting_type": "BROAD_KEYWORD"
      },
      "request": {
        "params": {
          "line_item_id": "619jl",
          "targeting_type": "BROAD_KEYWORD",
          "targeting_value": "technology",
          "account_id": "18ce54d4x5t"
        }
      }
    }

​

POST batch/accounts/:account_id/targeting_criteria

Permet de créer par lots de nouveaux critères de ciblage avec une seule requête.

Requêtes par lots

• La taille maximale actuelle d’un lot est de 500.
• 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, qu’il s’agisse d’erreur ou de succès, conservent l’ordre des éléments de la requête initiale.

Réponses par lots

Les réponses de l’API pour lots renvoient une collection ordonnée d’éléments. Pour le reste, elles sont identiques, en termes de structure, à leurs endpoints à élément unique correspondants.

Erreurs par lots

• Les erreurs au niveau de la requête (p. ex. taille maximale du lot dépassée) apparaissent dans la réponse sous l’objet errors.
• Les erreurs au niveau de l’élément (p. ex. paramètre requis des critères de ciblage manquant) apparaissent dans la réponse sous l’objet operation_errors.

URL de la ressource

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

Paramètres

Nom	Description
operation_type requis	Le type d’opération appliqué à chaque élément. Type: enum Valeurs possibles : Create, Delete
params requis	Un objet JSON contenant tous les paramètres des objets de critères de ciblage. Pour la liste des paramètres requis et optionnels des critères de ciblage, voir ici. De plus, cet endpoint prend en charge un paramètre operator_type qui fonctionne conjointement avec certaines valeurs de targeting_type. Les valeurs possibles pour ce paramètre sont EQ pour égal à, GTE pour supérieur ou égal à, LT pour inférieur à et NE pour différent de.

Exemple de requête

POST https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/targeting_criteria

    [
      {
        "operation_type":"Create",
        "params":{
          "line_item_id":"6f9an",
          "targeting_type":"LOCATION",
          "targeting_value":"5122804691e5fecc"
        }
      },
      {
        "operation_type":"Delete"
        "params":{
          "targeting_criterion_id":"al2rua"
        }
      }
    ]

Exemple de réponse

    {
      "data_type": "targeting_criterion",
      "data": [
        {
          "line_item_id": "6f9an",
          "name": "San Francisco–Oakland–San Jose CA, US",
          "id": "al7vt2",
          "location_type": "CITY",
          "operator_type": "EQ",
          "created_at": "2016-11-11T22:59:50Z",
          "targeting_value": "5122804691e5fecc",
          "updated_at": "2016-11-11T22:59:50Z",
          "deleted": false,
          "targeting_type": "LOCATION"
        },
        {
          "line_item_id": "6keuo",
          "name": "accounts",
          "id": "al2rua",
          "operator_type": "EQ",
          "created_at": "2016-11-11T17:50:19Z",
          "targeting_value": "accounts",
          "updated_at": "2016-11-11T22:59:50Z",
          "deleted": true,
          "targeting_type": "BROAD_KEYWORD"
        }
      ],
      "request": [
        {
          "params": {
            "line_item_id": "6f9an",
            "targeting_type": "LOCATION",
            "targeting_value": "5122804691e5fecc",
            "account_id": "18ce54d4x5t"
          },
          "operation_type": "Create",
        },
        {
          "params": {
            "targeting_criterion_id": "al2rua",
            "account_id": "18ce54d4x5t"
          },
          "operation_type": "Delete"
        }
      ]
    }

​

DELETE accounts/:account_id/targeting_criteria/:targeting_criterion_id

Supprime le critère de ciblage spécifié appartenant au compte actuel.

URL de la ressource

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

Paramètres

Nom	Description
account_id obligatoire	Identifiant du compte utilisé. Apparaît dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Exemple: 18ce54d4x5t
targeting_criterion_id obligatoire	Référence au critère de ciblage manipulé dans la requête. Type: string Exemple: dpl3a6

Exemple de requête

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria/dpl3a6

Exemple de réponse

    {
      "data": {
        "line_item_id": "8u94t",
        "name": "Ciblage d’audience personnalisée",
        "id": "dpl3a6",
        "created_at": "2017-05-26T03:29:35Z",
        "targeting_value": "249yj",
        "updated_at": "2017-08-30T18:38:58Z",
        "deleted": true,
        "targeting_type": "CUSTOM_AUDIENCE"
      },
      "request": {
        "params": {
          "targeting_criterion_id": "dpl3a6",
          "account_id": "18ce54d4x5t"
        }
      }
    }

​

Options de ciblage

Exécuter dans Postman

• Catégories de l’App Store
• Conversations
• Appareils
• Événements
• Centres d’intérêt
• Langues
• Emplacements
• Opérateurs de réseau
• Versions de la plateforme
• Plateformes
• Marchés TV
• Émissions TV

​

GET targeting_criteria/app_store_categories

Découvrez les critères de ciblage disponibles basés sur les catégories des app stores pour les Produits promus. Les catégories d’app store sont disponibles uniquement pour l’App Store iOS et le Google Play Store.

Le ciblage par catégorie d’applications installées permet de cibler des utilisateurs en fonction des catégories d’applications qu’ils ont installées ou pour lesquelles ils ont manifesté de l’intérêt.

Resource URL

https://ads-api.x.com/12/targeting_criteria/app_store_categories

Parameters

Name	Description
q optional	Paramètre query facultatif pour restreindre un critère de ciblage. Omettez ce paramètre pour récupérer l’ensemble des résultats. Type: string Exemple : music
os_type optional	Restreint les résultats à un app store spécifique. Type: enum Valeurs possibles : ANDROID, IOS

Example Request

GET https://ads-api.x.com/12/targeting_criteria/app_store_categories?q=music&os_type=IOS

Example Response

    {
      "data": [
        {
          "name": "Jeux : musique",
          "targeting_type": "APP_STORE_CATEGORY",
          "targeting_value": "qouq",
          "os_type": "IOS"
        },
        {
          "name": "Musique",
          "targeting_type": "APP_STORE_CATEGORY",
          "targeting_value": "qov2",
          "os_type": "IOS"
        }
      ],
      "request": {
        "params": {
          "q": "musique"
          "os_type": "IOS"
        }
      }
    }

​

GET targeting_criteria/conversations

Découvrez les critères de ciblage disponibles basés sur les conversations pour les produits sponsorisés.

Resource URL

https://ads-api.x.com/12/targeting_criteria/conversations

Parameters

Name	Description
conversation_type optional	Paramètre query facultatif permettant de restreindre à un certain type de conversation. Type: enum Valeurs possibles : ACTORS, ATHLETES, BOOK_GENRES, BOOKS, BRAND_CATEGORIES, BRANDS, CELEBRITIES, COACHES, DIGITAL_CREATORS, ENTERTAINMENT_BRANDS, ENTERTAINMENT_PERSONALITIES, FICTIONAL_CHARACTERS, JOURNALISTS, LIFESTYLES, MOVIE_GENRES, MOVIES, MUSIC_GENRES, MUSICIANS, NEWS_STORIES, NEWS, PERSONS, PLACES, PODCASTS, POLITICAL_AFFILIATIONS, POLITICIANS, PRODUCTS, RADIO_STATIONS, SPORTS_LEAGUES, SPORTS_PERSONALITIES, SPORTS_TEAMS, SPORTS, TRENDS, TV_SHOWS, VIDEO_GAME_PLATFORMS, VIDEO_GAME_PUBLISHERS, VIDEO_GAMES
count optional	Spécifie le nombre d’enregistrements à récupérer par requête. Type: int Par défaut : 200 Min, Max : 1, 1000
cursor optional	Spécifie un curseur pour obtenir la page de résultats suivante. Voir Pagination pour plus d’informations. Type: string Exemple : 8x7v00oow

Example Request

GET https://ads-api.x.com/12/targeting_criteria/conversations?count=2

Example Response

    {
      "request": {
        "params": {
          "count": 2
        }
      },
      "next_cursor": "1f7m7",
      "data": [
        {
          "targeting_type": "CONVERSATION",
          "targeting_value": "a1",
          "name": "NFL",
          "conversation_type": "SPORTS"
        },
        {
          "targeting_type": "CONVERSATION",
          "targeting_value": "a2",
          "name": "NBA",
          "conversation_type": "SPORTS"
        }
      ]
    }

​

GET targeting_criteria/devices

Découvrez les critères de ciblage disponibles basés sur l’appareil pour les produits sponsorisés. Le ciblage par appareil est disponible pour les Tweets sponsorisés.

URL de la ressource

https://ads-api.x.com/12/targeting_criteria/devices

Paramètres

Name	Description
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
q optional	Paramètre query facultatif pour restreindre un critère de ciblage. Omettez ce paramètre pour tout récupérer. Type: string Exemple : apple

Exemple de requête

GET https://ads-api.x.com/12/targeting_criteria/devices?count=2&q=iphone

Exemple de réponse

    {
      "data": [
        {
          "name": "iPhone 3GS",
          "manufacturer": "Apple",
          "os_type": "iOS",
          "targeting_value": "1q",
          "targeting_type": "DEVICE"
        },
        {
          "name": "iPhone 4",
          "manufacturer": "Apple",
          "os_type": "iOS",
          "targeting_value": "1r",
          "targeting_type": "DEVICE"
        }
      ],
      "request": {
        "params": {
          "q": "iphone",
          "count": 2
        }
      }
    }

​

GET targeting_criteria/events

Découvrez les critères de ciblage basés sur des événements disponibles pour les Produits sponsorisés. Un seul événement peut être ciblé par élément de campagne.

Remarque : Les événements existent souvent dans plusieurs fuseaux horaires, ce qui complique la prise en compte des heures d’événement dans une perspective inter‑fuseaux. Pour simplifier, toutes les valeurs start_time et end_time des événements sur cet endpoint sont exprimées en UTC±00:00, indépendamment de la langue et du fuseau horaire de l’événement. Il convient de garder cette conception à l’esprit lors des requêtes et des interactions avec les valeurs start_time et end_time des événements. Par exemple, l’Independence Day aux États‑Unis est représenté par start_time=2017-07-04T00:00:00Z et end_time=2017-07-05T00:00:00Z en UTC±00:00, évitant ainsi le problème de l’existence de ce jour férié sur plusieurs fuseaux horaires aux États‑Unis.

Resource URL

https://ads-api.x.com/12/targeting_criteria/events

Parameters

Name	Description
event_types required	Une query optionnelle pour restreindre à certains types d’événements. Type: enum Valeurs possibles : CONFERENCE, HOLIDAY, MUSIC_AND_ENTERTAINMENT, OTHER, POLITICS, RECURRING, SPORTS
count optional	Spécifie le nombre d’enregistrements à tenter de récupérer par requête distincte. Type: int Par défaut : 200 Min, Max : 1, 1000
country_codes optional	Une query optionnelle pour restreindre une recherche de critères de ciblage à certains pays à l’aide du code pays ISO à 2 lettres. Si ce paramètre n’est pas spécifié, tous les événements sont renvoyés. Type: string
cursor optional	Spécifie un curseur pour obtenir la page suivante de résultats. Voir Pagination pour plus d’informations. Type: string Exemple : 8x7v00oow
end_time optional	L’heure, exprimée en ISO 8601, à laquelle la campagne se terminera. Type: string Exemple : 2017-10-05T00:00:00Z
start_time optional	L’heure, exprimée en ISO 8601, à laquelle l’élément de campagne commencera à être diffusé. Remarque : Par défaut, l’heure actuelle est utilisée. Type: string Exemple : 2017-07-05T00:00:00Z

Example Request

GET https://ads-api.x.com/12/targeting_criteria/events?count=1

Example Response

    {
      "request": {
        "params": {
          "count": 1
        }
      },
      "data_type": "events",
      "data": [
        {
          "reach": {
            "total_reach": null
          },
          "name": "Nouvel An",
          "start_time": "2017-12-31T00:00:00Z",
          "top_users": [],
          "top_tweets": [],
          "top_hashtags": [],
          "gender_breakdown_percentage": {},
          "end_time": "2018-01-02T00:00:00Z",
          "country_code": null,
          "device_breakdown_percentage": {},
          "targeting_value": "1ex",
          "is_global": true,
          "event_type": "HOLIDAY"
          "country_breakdown_percentage": {}
        }
      ],
      "next_cursor": "uww0"
    }

​

GET targeting_criteria/interests

Découvrez les critères de ciblage par centres d’intérêt disponibles pour les Produits sponsorisés. Les centres d’intérêt évoluent rarement ; nous vous recommandons toutefois d’actualiser cette liste au moins une fois par semaine.

Resource URL

https://ads-api.x.com/12/targeting_criteria/interests

Parameters

Name	Description
count optional	Indique le nombre d’enregistrements à tenter de récupérer par requête distincte. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Indique un curseur pour obtenir la page suivante de résultats. Voir Pagination pour plus d’informations. Type: string Example: 8x7v00oow
q optional	Une query facultative pour restreindre les critères de ciblage. Omettez ce paramètre pour tout récupérer. Type: string Example: books

Example Request

GET https://ads-api.x.com/12/targeting_criteria/interests?q=books

Example Response

    {
      "data": [
        {
          "name": "Livres et littérature/Biographies et mémoires",
          "targeting_type": "INTEREST",
          "targeting_value": "1001"
        }
      ],
      "request": {
        "params": {
          "q": "livres",
          "count": 1
        }
      },
      "next_cursor": "6by4n4"
    }

​

GET targeting_criteria/languages

Découvrez les langues disponibles pour le ciblage.

Resource URL

https://ads-api.x.com/12/targeting_criteria/languages

Parameters

Name	Description
count optional	Indique le nombre d’enregistrements à tenter de récupérer par requête distincte. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Indique un curseur pour obtenir la page suivante de résultats. Voir Pagination pour plus d’informations. Type: string Example: 8x7v00oow
q optional	Paramètre query facultatif pour restreindre un critère de ciblage. Omettez ce paramètre pour tout récupérer. Type: string Example: english

Example Request

GET https://ads-api.x.com/12/targeting_criteria/languages?q=english

Example Response

    {
      "data": [
        {
          "name": "Anglais",
          "targeting_type": "LANGUAGE",
          "targeting_value": "en"
        }
      ],
      "request": {
        "params": {
          "q": "anglais"
        }
      },
      "next_cursor": null
    }

​

GET targeting_criteria/locations

Découvrez les critères de ciblage géographique disponibles pour les Produits sponsorisés. Le géociblage est disponible pour les Comptes sponsorisés et les Tweets sponsorisés au niveau du pays, de l’État/région, de la ville et du code postal. Le ciblage par code postal doit être utilisé si vous souhaitez récupérer des analyses au niveau du code postal.

Remarque : Pour récupérer des villes ciblables spécifiques, telles que San Francisco ou New York, utilisez l’énumération CITIES avec le paramètre de requête location_type.

Pour cibler les Designated Market Areas (DMA), utilisez l’énumération METROS.

URL de la ressource

https://ads-api.x.com/12/targeting_criteria/locations

Paramètres

Nom	Description
count facultatif	Spécifie le nombre d’enregistrements à tenter de récupérer par requête distincte. Type : int Par défaut : 200 Min, Max : 1, 1000
country_code facultatif	Paramètre facultatif permettant de restreindre la recherche de critères de ciblage à un pays spécifique via le code pays ISO à 2 lettres. Omettez ce paramètre pour récupérer les résultats pour tous les pays. Type : string Exemple : JP
cursor facultatif	Spécifie un curseur pour obtenir la page suivante de résultats. Voir Pagination pour plus d’informations. Type : string Exemple : 8x7v00oow
location_type facultatif	Restreint les résultats à un type de localisation spécifique. Un ciblage plus fin que COUNTRIES peut ne pas être disponible partout. Type : enum Valeurs possibles : COUNTRIES, REGIONS, METROS, CITIES, POSTAL_CODES
q facultatif	Paramètre facultatif permettant de restreindre une recherche de critères de ciblage. Omettez ce paramètre pour récupérer tous les résultats. Type : string Exemple : New York

Exemple de requête

GET https://ads-api.x.com/12/targeting_criteria/locations?location_type=CITIES&q=los angeles

Exemple de réponse

    {
      "data": [
        {
          "name": "Los Angeles, Los Angeles CA, CA, États-Unis",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "3b77caf94bfc81fe",
          "targeting_type": "LOCATION"
        },
        {
          "name": "East Los Angeles, Los Angeles CA, CA, États-Unis",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "67571a7baaa5906b",
          "targeting_type": "LOCATION"
        },
        {
          "name": "Lake Los Angeles, Los Angeles CA, CA, États-Unis",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "ea9bfbd43c93400f",
          "targeting_type": "LOCATION"
        },
        {
          "name": "Los Gatos, San Francisco–Oakland–San Jose CA, CA, États-Unis",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "a2de7c70b82b0ca0",
          "targeting_type": "LOCATION"
        },
        {
          "name": "Los Altos, Monterey–Salinas CA, CA, États-Unis",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "6a4364ea6f987c10",
          "targeting_type": "LOCATION"
        },
        {
          "name": "Los Banos, CA, États-Unis",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "b1b6fc646de75904",
          "targeting_type": "LOCATION"
        },
        {
          "name": "Los Alamitos, Los Angeles CA, CA, États-Unis",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "0799ff0a3c1006e9",
          "targeting_type": "LOCATION"
        },
        {
          "name": "Los Angeles, États-Unis",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "019940ae78c7b3bc",
          "targeting_type": "LOCATION"
        }
      ],
      "request": {
        "params": {
          "location_type": "CITIES",
          "q": "los angeles"
        }
      },
      "next_cursor": null
    }

​

GET targeting_criteria/network_operators

Découvrez les critères de ciblage disponibles basés sur les opérateurs mobiles pour les Produits sponsorisés.

Cet endpoint vous permet de rechercher des opérateurs ciblables, tels qu’AT&T, Verizon, Sprint, T-Mobile, etc., dans plusieurs pays.

Resource URL

https://ads-api.x.com/12/targeting_criteria/network_operators

Parameters

Name	Description
count optional	Spécifie le nombre d’enregistrements à tenter de récupérer par requête distincte. Type: int Default: 200 Min, Max: 1, 1000
country_code optional	Paramètre query optionnel pour limiter la recherche de critères de ciblage à un pays spécifique à l’aide du code pays ISO à 2 lettres. Si ce paramètre n’est pas spécifié, seules les audiences partenaires pour les États-Unis sont renvoyées. Type: string Default: US
cursor optional	Spécifie un curseur pour obtenir la page suivante de résultats. Voir Pagination pour plus d’informations. Type: string Example: 8x7v00oow
q optional	Paramètre query optionnel pour restreindre une recherche de critères de ciblage. Omettez ce paramètre pour récupérer tous les résultats. Type: string Examples: Airpeak

Example Request

GET https://ads-api.x.com/12/targeting_criteria/network_operators?count=5&country_code=US

Example Response

    {
      "data": [
        {
          "country_code": "US",
          "targeting_type": "NETWORK_OPERATOR",
          "name": "Advantage",
          "targeting_value": "2l"
        },
        {
          "country_code": "US",
          "targeting_type": "NETWORK_OPERATOR",
          "name": "Aeris",
          "targeting_value": "1b"
        },
        {
          "country_code": "US",
          "targeting_type": "NETWORK_OPERATOR",
          "name": "Airadigm",
          "targeting_value": "2t"
        },
        {
          "country_code": "US",
          "targeting_type": "NETWORK_OPERATOR",
          "name": "Airlink PCS",
          "targeting_value": "14"
        },
        {
          "country_code": "US",
          "targeting_type": "NETWORK_OPERATOR",
          "name": "Airpeak",
          "targeting_value": "1i"
        }
      ],
      "request": {
        "params": {
          "country_code": "US",
          "count": 5
        }
      },
      "next_cursor": "o7x9iet1a5u608olj4"
    }

​

GET targeting_criteria/platform_versions

Découvrez les critères de ciblage disponibles basés sur les versions de systèmes d’exploitation mobiles pour les produits promus. Le ciblage par version de plateforme est disponible pour les comptes promus et les Tweets promus. Cela permet de cibler jusqu’à la version de correctif d’un système d’exploitation mobile, comme Android 8.0 ou iOS 10.0.

URL de la ressource

https://ads-api.x.com/12/targeting_criteria/platform_versions

Paramètres

Nom	Description
q optional	Une query facultative pour restreindre la recherche de critères de ciblage. Omettez ce paramètre pour récupérer tous les résultats. Type: string Examples: jelly bean

Exemple de requête

GET https://ads-api.x.com/12/targeting_criteria/platform_versions

Exemple de réponse

    {
        "data": [
            {...},
            {
                "name": "Ice Cream Sandwich",
                "number": "4.0",
                "os_type": "Android",
                "targeting_type": "PLATFORM_VERSION",
                "targeting_value": "17"
            },
            {
                "name": "Jelly Bean",
                "number": "4.1",
                "os_type": "Android",
                "targeting_type": "PLATFORM_VERSION",
                "targeting_value": "18"
            },
            {...}
        ],
        "data_type": "targeting_criterion"
        "request": {
            "params": {}
        }
    }

​

GET targeting_criteria/platforms

Découvrez les critères de ciblage disponibles basés sur la plateforme pour les Produits sponsorisés.

URL de la ressource

https://ads-api.x.com/12/targeting_criteria/platforms

Paramètres

Nom	Description
count facultatif	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
q facultatif	Paramètre query facultatif permettant de restreindre la recherche de critères de ciblage. Omettez ce paramètre pour récupérer tous les résultats. Type : string Exemples : ios, blackberry
lang facultatif	Code de langue ISO-639-1. Lorsque ce paramètre est fourni, un attribut additional localized_name est renvoyé dans la réponse. Type : int, string Exemple : fr

Exemple de requête

GET https://ads-api.x.com/12/targeting_criteria/platforms

Exemple de réponse

    {
      "data": [
        {
          "name": "iOS",
          "targeting_type": "PLATFORM",
          "targeting_value": "0"
        },
        {
          "name": "Android",
          "targeting_type": "PLATFORM",
          "targeting_value": "1"
        },
        {
          "name": "Téléphones et tablettes BlackBerry",
          "targeting_type": "PLATFORM",
          "targeting_value": "2"
        },
        {
          "name": "Web mobile sur d’autres appareils",
          "targeting_type": "PLATFORM",
          "targeting_value": "3"
        },
        {
          "name": "Ordinateurs de bureau et portables",
          "targeting_type": "PLATFORM",
          "targeting_value": "4"
        }
      ],
      "request": {
        "params": {}
      }
    }

​

GET targeting_criteria/tv_markets

Découvrez les marchés TV disponibles où il est possible de cibler des émissions TV. Renvoie les marchés par langue/région pouvant être utilisés pour interroger l’endpoint GET targeting_criteria/tv_shows.

Resource URL

https://ads-api.x.com/12/targeting_criteria/tv_markets

Parameters

Aucun

Example Request

GET https://ads-api.x.com/12/targeting_criteria/tv_markets

Example Response

    {
      "data": [
        {
          "name": "France",
          "country_code": "FR",
          "locale": "fr-FR"
        },
        {
          "name": "Chili",
          "country_code": "CL",
          "locale": "es-CL"
        },
        {
          "name": "Allemagne",
          "country_code": "DE",
          "locale": "de-DE"
        },
        {
          "name": "Pays-Bas",
          "country_code": "NL",
          "locale": "nl-NL"
        },
        {
          "name": "États-Unis",
          "country_code": "US",
          "locale": "en-US"
        },
        {
          "name": "Venezuela",
          "country_code": "VE",
          "locale": "es-VE"
        },
        {
          "name": "Brésil",
          "country_code": "BR",
          "locale": "pt-BR"
        },
        {
          "name": "Mexique",
          "country_code": "MX",
          "locale": "es-MX"
        },
        {
          "name": "Colombie",
          "country_code": "CO",
          "locale": "es-CO"
        },
        {
          "name": "Royaume-Uni",
          "country_code": "GB",
          "locale": "en-GB"
        },
        {
          "name": "Argentine",
          "country_code": "AR",
          "locale": "es-AR"
        },
        {
          "name": "Japon",
          "country_code": "JP",
          "locale": "ja-JP"
        },
        {
          "name": "Canada",
          "country_code": "CA",
          "locale": "en-CA"
        },
        {
          "name": "Espagne",
          "country_code": "ES",
          "locale": "es-ES"
        },
        {
          "name": "Italie",
          "country_code": "IT",
          "locale": "it-IT"
        },
        {
          "name": "États-Unis - Hispaniques",
          "country_code": "US",
          "locale": "es-US"
        },
        {
          "name": "Irlande",
          "country_code": "IE",
          "locale": "en-IE"
        }
      ],
      "request": {
        "params": {}
      }
    }

​

GET targeting_criteria/tv_shows

Découvrez les critères de ciblage disponibles basés sur les émissions TV pour les Produits Promoted. Le ciblage par émission TV est disponible pour les Promoted Tweets dans certains marchés. Consultez l’endpoint GET targeting_criteria/tv_markets pour les marchés disponibles.

Remarque : Toute audience contenant moins de 1 000 utilisateurs apparaîtra avec une valeur estimated_users de 1000.

Remarque : Les options de ciblage par chaîne TV et par genre ne sont plus prises en charge.

Resource URL

https://ads-api.x.com/12/targeting_criteria/tv_shows

Parameters

Name	Description
locale required	Paramètre requis qui spécifie le tv_market_locale à interroger pour les émissions TV disponibles. Les marchés TV sont interrogés en fonction de la valeur locale renvoyée par GET targeting_criteria/tv_markets. Type: string Example: en-US
count optional	Spécifie le nombre d’enregistrements à récupérer par requête. Type: int Default: 50 Min, Max: 1, 50
cursor optional	Spécifie un curseur pour obtenir la page suivante de résultats. Voir Pagination pour plus d’informations. Type: string Example: 8x7v00oow
q optional	Paramètre query facultatif pour restreindre la recherche de critères de ciblage. Omettez ce paramètre pour récupérer tous les résultats. Type: string Examples: ios, blackberry

Example Request

GET https://ads-api.x.com/12/targeting_criteria/tv_shows?locale=en-US&q=news&count=1

Example Response

    {
      "data": [
        {
          "name": "NewsWatch",
          "targeting_value": 10027243420,
          "genre": "PAID",
          "locales": [
            {
              "language": "en",
              "country": "US"
            }
          ]
        }
      ],
      "next_cursor": "c-22838-zdQDJrTxSvOYfQOhb2IlGQ",
      "request": {
        "params": {
          "locale": {
            "countryCode": "US",
            "languageCode": "en"
          },
          "count": 1,
          "q": "news"
        }
      }
    }

​

Suggestions de ciblage

Exécuter dans Postman

​

GET accounts/:account_id/targeting_suggestions

Obtenez jusqu’à 50 suggestions de ciblage par mot-clé ou par utilisateur pour compléter votre sélection initiale.

URL de la ressource

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

Paramètres

Name	Description
account_id required	L’identifiant du compte exploité. Figure dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte indiqué doit être associé à l’utilisateur s’authentifiant. Type: string Exemple: 18ce54d4x5t
suggestion_type required	Indique le type de suggestions à renvoyer. Type: enum Valeurs possibles: KEYWORD, USER_ID
targeting_values required	Liste, séparée par des virgules, de mots-clés ou d’identifiants d’utilisateurs servant à alimenter les suggestions. Remarque : ces deux types de suggestions ne peuvent pas être mélangés. Exemple: 756201191646691328
count optional	Indique le nombre d’enregistrements à tenter de récupérer par requête distincte. Type: int Valeur par défaut: 30 Min, Max: 1, 50

Exemple de requête

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_suggestions?suggestion_type=KEYWORD&targeting_values=developers&count=2"

Exemple de réponse

    {
      "data": [
        {
          "suggestion_type": "KEYWORD",
          "suggestion_value": "devs"
        },
        {
          "suggestion_type": "KEYWORD",
          "suggestion_value": "software"
        }
      ],
      "request": {
        "params": {
          "suggestion_type": "KEYWORD",
          "targeting_values": [
            "developers"
          ],
          "count": 2,
          "account_id": "18ce54d4x5t"
        }
      }
    }

​

Paramètres fiscaux

Exécuter dans Postman

​

GET accounts/:account_id/tax_settings

Récupère les détails des paramètres fiscaux associés au compte actuel.

URL de la ressource

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

Paramètres

Nom	Description
account_id requis	L’identifiant du compte exploité. Apparaît dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t

Exemple de requête

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tax_settings

Exemple de réponse

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "tax_id": "GB896391250",
        "business_relationship": "SELF",
        "business_relationship": "SELF",
        "address_street1": "21 March St",
        "address_last_name": null,
        "address_company": "ABC, Inc.",
        "tax_category": "BUSINESS_WITH_VAT",
        "address_postal_code": "SW1A 1AA",
        "bill_to": "NOT_SET",
        "address_region": "London",
        "address_country": "GB",
        "address_first_name": null,
        "invoice_jurisdiction": "NOT_SET"
        "address_street2": null,
        "address_email": null
      }
    }

​

PUT accounts/:account_id/tax_settings

Met à jour les paramètres fiscaux du compte en cours.

URL de ressource

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

Paramètres

Nom	Description
account_id required	L’identifiant du compte utilisé. Figure dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Ads, à l’exception de GET accounts. Le compte indiqué doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
address_city optional	La ville de l’adresse du propriétaire du compte. Type : string Exemple : San Francisco
address_country optional	Le code pays à deux lettres de l’adresse du propriétaire du compte. Type : string Exemple : US
address_email optional	L’adresse e‑mail associée à l’adresse du propriétaire du compte. Type : string Exemple : [e-mail]
address_first_name optional	Le prénom du propriétaire du compte. Type : string Exemple : API
address_last_name optional	Le nom de famille du propriétaire du compte. Type : string Exemple : McTestface
address_name optional	Le nom de l’entreprise du propriétaire du compte. Type : string Exemple : ABC, Co.
address_postal_code optional	Le code postal de l’adresse du propriétaire du compte. Type : string Exemple : 94102
address_region optional	La région de l’adresse du propriétaire du compte. Type : string Exemple : California
address_street1 optional	La première ligne de l’adresse du propriétaire du compte. Type : string Exemple : 21 March St
address_street2 optional	La deuxième ligne de l’adresse du propriétaire du compte. Type : string Exemple : Suite 99
bill_to optional	L’entité facturée. Type : enum Valeurs possibles : ADVERTISER, AGENCY
business_relationship optional	Indique si le compte appartient à l’annonceur ou à l’agence. Type : enum Valeurs possibles : AGENCY, SELF
client_address_city optional	La ville de l’adresse de l’annonceur. À renseigner lorsque le compte publicitaire est détenu par une agence. Type : string Exemple : Toronto
client_address_country optional	Le code pays à deux lettres de l’adresse de l’annonceur. À renseigner lorsque le compte publicitaire est détenu par une agence. Type : string Exemple : CA
client_address_email optional	L’adresse e‑mail associée à l’adresse de l’annonceur. À renseigner lorsque le compte publicitaire est détenu par une agence. Type : string Exemple : [e-mail]
client_address_first_name optional	Le prénom de l’annonceur. À renseigner lorsque le compte publicitaire est détenu par une agence. Type : string Exemple : Brand
client_address_last_name optional	Le nom de famille de l’annonceur. À renseigner lorsque le compte publicitaire est détenu par une agence. Type : string Exemple : Advertiser
client_address_name optional	Le nom de l’entreprise de l’annonceur. À renseigner lorsque le compte publicitaire est détenu par une agence. Type : string Exemple : Brand, Inc.
client_address_postal_code optional	Le code postal de l’adresse de l’annonceur. À renseigner lorsque le compte publicitaire est détenu par une agence. Type : string Exemple : M5H 2N2
client_address_region optional	La région de l’adresse de l’annonceur. À renseigner lorsque le compte publicitaire est détenu par une agence. Type : string Exemple : Ontario
client_address_street1 optional	La première ligne de l’adresse de l’annonceur. À renseigner lorsque le compte publicitaire est détenu par une agence. Type : string Exemple : 280 Queen St W
client_address_street2 optional	La deuxième ligne de l’adresse de l’annonceur. À renseigner lorsque le compte publicitaire est détenu par une agence. Type : string Exemple : The 6
invoice_jurisdiction optional	Juridiction de facturation. Type : enum Valeurs possibles : LOI_SAPIN, NONE, NOT_SET
tax_category optional	Indique si la fiscalité doit être individuelle ou professionnelle. Type : enum Valeurs possibles : BUSINESS_NO_VAT, BUSINESS_WITH_VAT, INDIVIDUAL
tax_exemption_id optional	ID d’exonération de TVA. Type : string Exemple : 12345
tax_id optional	ID d’immatriculation à la TVA. Type : string Exemple : 67890

Exemple de requête

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/tax_settings?address_name=ABC, Co.

Exemple de réponse

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "address_name": "ABC Co."
        }
      },
      "data": {
        "tax_id": "GB896391250",
        "address_city": "Londres",
        "business_relationship": "SELF",
        "address_street1": "21 March St",
        "address_last_name": null,
        "address_company": "ABC Co.",
        "tax_category": "BUSINESS_WITH_VAT",
        "address_postal_code": "SW1A 1AA",
        "bill_to": "NOT_SET",
        "address_region": "Londres",
        "address_country": "GB",
        "address_first_name": null,
        "invoice_jurisdiction": "NOT_SET",
        "address_street2": null,
        "address_email": null
      }
    }

​

Balises de suivi

Exécuter dans Postman

​

GET accounts/:account_id/tracking_tags

Récupérer les détails de certaines ou de toutes les balises de suivi associées au compte actuel.

URL de la ressource

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

Paramètres

Name	Description
account_id required	L’identifiant du compte exploité. Apparaît dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: 18ce54d4x5t
count optional	Spécifie le nombre d’enregistrements à récupérer par requête distincte. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Spécifie un curseur pour obtenir la page suivante de résultats. Voir Pagination pour plus d’informations. Type: string Example: 8x7v00oow
line_item_ids optional	Limite la réponse aux seules balises de suivi associées à des line items spécifiques en fournissant une liste d’identifiants séparés par des virgules. Jusqu’à 200 IDs peuvent être fournis. Type: string Example: 96uzp
sort_by optional	Trie selon un attribut pris en charge, par ordre croissant ou décroissant. Voir Sorting pour plus d’informations. Type: string Example: created_at-asc
tracking_tag_ids optional	Limite la réponse aux seules balises de suivi souhaitées en fournissant une liste d’identifiants séparés par des virgules. Jusqu’à 200 IDs peuvent être fournis. Type: string Example: 3m82
with_deleted optional	Inclure les résultats supprimés dans la requête. Type: boolean Default: false Possible values: true, false
with_total_count optional	Inclure l’attribut de réponse total_count. Remarque : Ce paramètre et cursor sont mutuellement exclusifs. Remarque : Les requêtes incluant total_count auront des limites de taux plus basses, actuellement fixées à 200 par 15 minutes. Type: boolean Default: false Possible values: true, false

Exemple de requête

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags?tracking_tag_ids=3m82

Exemple de réponse

    {
      "request": {
        "params": {
          "tracking_tag_ids": [
            "3m82"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "line_item_id": "fdwcl",
          "tracking_tag_url": "https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309",
          "tracking_tag_type": "IMPRESSION_TAG",
          "id": "3m82",
          "created_at": "2019-06-26T17:04:26Z",
          "updated_at": "2019-06-26T17:04:26Z",
          "deleted": false
        }
      ]
    }

​

GET accounts/:account_id/tracking_tags/:tracking_tag_id

Récupère une balise de suivi spécifique associée au compte actuel.

URL de la ressource

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

Paramètres

Name	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte indiqué doit être associé à l’utilisateur authentifié. Type: string Exemple : 18ce54d4x5t
tracking_tag_id required	Référence de la balise de suivi utilisée dans la requête. Type: string Exemple : 555j
with_deleted optional	Inclure les résultats supprimés dans la réponse. Type: boolean Valeur par défaut : false Valeurs possibles : true, false

Exemple de requête

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags/555j

Exemple de réponse

    {
      "request": {
        "params": {
          "with_deleted": true,
          "tracking_tag_id": "555j",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "72v2x",
        "tracking_tag_url": "https://ad.doubleclick.net/ddm/trackimp/N6344.2061500TWITTER-OFFICIAL/B23028778.279118262;dc_trk_aid=473354132;dc_trk_cid=119658253",
        "tracking_tag_type": "IMPRESSION_TAG"
        "id": "555j",
        "created_at": "2020-08-13T23:02:03Z",
        "updated_at": "2020-08-13T23:02:03Z",
        "deleted": false
      }
    }

​

POST accounts/:account_id/tracking_tags

Associer une balise de suivi à l’élément de campagne (line item) spécifié.

URL de la ressource

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

Paramètres

Nom	Description
account_id obligatoire	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
line_item_id obligatoire	La référence de l’élément de campagne (line item) ciblé par la requête. Type : string Exemple : 8v7jo
tracking_tag_type obligatoire	Le type de balise de suivi. Type : enum Valeurs possibles : IMPRESSION_TAG, CLICK_TRACKER
tracking_tag_url obligatoire	L’URL de la balise de suivi fournie par le partenaire de tracking. Type : string Exemple : https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309

Exemple de requête

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags?line_item_id=fdwcl&tracking_tag_type=IMPRESSION_TAG&tracking_tag_url=https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309

Exemple de réponse

    {
      "request": {
        "params": {
          "line_item_id": "fdwcl",
          "tracking_tag_type": "IMPRESSION_TAG",
          "tracking_tag_url": "https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "fdwcl",
        "tracking_tag_url": "https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309",
        "tracking_tag_type": "IMPRESSION_TAG",
        "id": "3m82",
        "created_at": "2019-06-26T17:04:26Z",
        "updated_at": "2019-06-26T17:04:26Z",
        "deleted": false
      }
    }

​

PUT accounts/:account_id/tracking_tags/:tracking_tag_id

Associer une balise de suivi à l’élément de ligne spécifié.

URL de ressource

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

Paramètres

Nom	Description
account_id obligatoire	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
tracking_tag_url obligatoire	L’URL de la balise de suivi fournie par le partenaire de suivi. Type : string Exemple : https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309

Exemple de requête

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags/3m82?tracking_tag_url=https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309

Exemple de réponse

    {
      "request": {
        "params": {
          "tracking_tag_id": "3m82",
          "tracking_tag_url": "https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "fdwcl",
        "tracking_tag_url": "https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309",
        "tracking_tag_type": "IMPRESSION_TAG",
        "id": "3m82",
        "created_at": "2019-06-26T17:04:26Z",
        "updated_at": "2022-01-26T17:04:26Z",
        "deleted": false
      }
    }

​

DELETE accounts/:account_id/tracking_tags/:tracking_tag_id

Dissocie une balise de suivi de l’élément de campagne (line item) spécifié.

URL de la ressource

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

Paramètres

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

Exemple de requête

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags/555j

Exemple de réponse

    {
      "request": {
        "params": {
          "tracking_tag_id": "555j",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "72v2x",
        "tracking_tag_url": "https://ad.doubleclick.net/ddm/trackimp/N6344.2061500TWITTER-OFFICIAL/B23028778.279118262;dc_trk_aid=473354132;dc_trk_cid=119658253",
        "tracking_tag_type": "IMPRESSION_TAG",
        "id": "555j",
        "created_at": "2020-08-13T23:02:03Z",
        "updated_at": "2021-08-29T17:12:58Z",
        "deleted": true
      }
    }

​

Paramètres utilisateur

Exécuter dans Postman

(https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87)

​

GET accounts/:account_id/user_settings/:user_id

Récupère les paramètres de l’utilisateur.

URL de la ressource

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

Paramètres

Nom	Description
account_id requis	L’identifiant du compte exploité. Figure dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
user_id requis	Référence à l’utilisateur au nom duquel vous effectuez la requête. Utilisez GET users/lookup pour récupérer un id d’utilisateur à partir d’un nom d’utilisateur. Type : long Exemple : 756201191646691328

Exemple de requête

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/user_settings/756201191646691328

Exemple de réponse

      {
        "request": {
          "params": {
            "account_id": "18ce54d4x5t",
            "user_id": "756201191646691328"
          }
        },
        "data": {
          "notification_email": "[e-mail]",
          "contact_phone": "",
          "contact_phone_extension": ""
        }
      }

​

PUT accounts/:account_id/user_settings/:user_id

Met à jour les paramètres de l’utilisateur. Nécessite un contexte utilisateur. Non accessible aux administrateurs du compte.

URL de la ressource

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

Paramètres

Nom	Description
account_id requis	Identifiant du compte utilisé. Apparaît dans le chemin de la ressource et dans GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
user_id requis	Référence à l’utilisateur au nom duquel la requête est effectuée. Utilisez GET users/lookup pour récupérer un id d’utilisateur à partir d’un nom d’écran. Type : long Exemple : 756201191646691328
notification_email optionnel	Adresse e‑mail à utiliser pour les notifications du compte. Type : string Exemple : [e-mail]
contact_phone optionnel	Numéro de téléphone de contact. Type : string Exemple : 202-555-0128
contact_phone_extension optionnel	Poste pour le contact contact_phone. Type : string Exemple : 1234

Exemple de requête

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/user_settings/756201191646691328?notification_email='[e-mail]'&subscribe_email_types=ACCOUNT_PERFORMANCE,PERFORMANCE_IMPROVEMENT"

Exemple de réponse

      {
        "request": {
          "params": {
            "account_id": "18ce54d4x5t",
            "user_id": "756201191646691328"
            "notification_email": "[e-mail]",
            "subscribed_campaign_events": [
              "PERFORMANCE_DU_COMPTE",
              "AMÉLIORATION_DES_PERFORMANCES"
            ]
          }
        },
        "data": {
          "notification_email": "[e-mail]",
          "contact_phone": "",
          "Contact_phone_extension": ""
        }
      }