Gestion des campagnes

​

API pour les annonceurs

Planifiez des campagnes et gérez des publicités sur X de façon programmatique grâce à cette suite d’API.

​

Que pouvez-vous promouvoir ?

​

Annonces sponsorisées

• Les annonces sponsorisées sont des publicités classiques achetées par des annonceurs qui souhaitent toucher un groupe d’utilisateurs plus large ou susciter l’engagement de leurs abonnés existants.
• Les annonces sponsorisées sont clairement identifiées comme sponsorisées lorsqu’un annonceur paie pour leur diffusion sur X. À tous les autres égards, les annonces sponsorisées se comportent comme des publicités classiques et peuvent être repartagées, recevoir des réponses, être aimées (likées), etc. Elles suivent des règles de diffusion classiques et sont créées à l’aide de POST statuses/update.
• Les Tweets « promoted-only », créés via POST accounts/:account_id/tweet, peuvent être utilisés dans des campagnes de Tweets sponsorisés, mais ne seront pas diffusés auprès des abonnés ni affichés sur le fil public. Pour récupérer la liste des Tweets « promoted-only » pour un certain compte, utilisez GET accounts/:account_id/scoped_timeline.

​

Comptes sponsorisés

• Les comptes sponsorisés font partie de Who to Follow (Qui suivre), qui suggère des comptes que les utilisateurs ne suivent pas encore et qu’ils peuvent trouver intéressants. Les comptes sponsorisés permettent de présenter une gamme encore plus large de comptes susceptibles de leur 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’API Ads.

​

Campagnes et groupes d’annonces (line items)

Les campagnes définissent le calendrier et le budget d’une campagne publicitaire. 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 dérouler en continu jusqu’à épuisement du budget. Le budget provient de l’un des Funding Instruments du compte publicitaire. Les identifiants de campagne (:campaign_id) sont la représentation en base 36 de la valeur en base 10 que nous présentons 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’à ce qu’elle atteigne son heure de fin ou qu’elle soit supprimée. Les campagnes en pause sont considérées comme actives jusqu’à leurs dates de fin prévues.

Les line items consomment 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

L’API X Ads propose un ensemble d’endpoints d’analytics pour suivre et optimiser les performances des publicités. Veuillez consulter Analytics et Analytics Best Practices pour plus d’informations.

Pour la métrique de facturation, les données peuvent ne pas être finalisées avant trois jours après l’événement. Avant ce délai, les données doivent être considérées comme provisoires. La valeur finale facturable sera toujours inférieure au montant provisoire. La valeur facturable est corrigée pour tenir compte du spam et du trafic de faible qualité associé. Consultez Timezones pour d’autres considérations liées au temps.

​

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

L’exemple suivant part du principe 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 proprement l’authentification OAuth de X. twurl est un excellent outil pour tester et déboguer rapidement les fonctionnalités de l’Ads API (et de l’API REST). Pour afficher l’intégralité des en-têtes de la requête et de la réponse, utilisez -t pour tracer l’appel, ce qui revient à peu près à l’option -v de cURL.

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

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

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

{
  "request": {
    "params": {
    }
  },
  "data": [
    {
      "name": "Test account for @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’identifiant de l’instrument de financement.

Appelez l’API GET accounts/:account_id/funding_instruments en utilisant l’identifiant du compte récupéré à l’étape 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 et une heure de début ainsi qu’un budget pour la campagne. Pour cet exemple, nous allons utiliser un budget de 500 $et, pour la limite quotidienne, 50$.

twurl -H ads-api.x.com -d "funding_instrument_id=yyyy&name=My First Campaign&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": "My First Campaign",
    "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": "My First Campaign",
      "total_budget_amount_local_micro": 500000000
    }
  }
}

4. Créez un élément de campagne (line item) associé à la campagne.

Maintenant que nous avons un id de campagne, nous pouvons créer un élément de campagne à lui associer. L’élément de campagne regroupe le montant de l’enchère, le ciblage et la partie créative proprement dite de la campagne. Pour cet élément de campagne, 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": "Untitled",
    "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 campagne.

Une fois l’élément de campagne créé, nous pouvons lui attribuer des critères de ciblage. Nous voulons cibler les mots-clés de l’expression « grumpy cat » dans la région de la baie de San Francisco. Cela va nécessiter une recherche de l’id de localisation 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 Jose CA, US",
      "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 campagne.

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

Et voilà ! Nous avons maintenant une campagne de Tweets sponsorisés dans les timelines, active, ciblée et dotée d’un budget, qui est en cours de diffusion.

​

Campagnes basées sur un objectif

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

Le paramètre utilisé dans les endpoints d’écriture de line item, et renvoyé dans 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 ont un impact sur la façon dont nous optimisons les campagnes dans nos enchères et sur la façon dont nous facturons ces campagnes. Nous permettons une tarification basée sur l’objectif, comme le CPAC pour APP_ENGAGEMENTS, le CPAC ou le CPI pour APP_INSTALLS, le CPLC pour WEBSITE_CLICKS, le CPF pour FOLLOWERS, le CPE pour ENGAGEMENTS et le CPM pour REACH.

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

Remarque : Les 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édias dans les Tweets	Modèle de tarification
Réengagements avec l’app	APP_ENGAGEMENTS	Carte de téléchargement d’app avec image ou vidéo requise.	CPAC
Installations d’app	APP_INSTALLS	Carte de téléchargement d’app avec image ou vidéo requise.	CPAC ou CPI (défini via charge_by)
Reach	REACH	Aucune restriction.	CPM
Followers	FOLLOWERS	Tweet non requis, mais recommandé. Il n’y a aucune restriction sur les médias des Tweets pour les campagnes Followers, bien que nous recommandions des Tweets composés uniquement de texte. Plus d’informations	CPF
Engagements	ENGAGEMENTS	Aucune restriction.	CPE
Vues de vidéo	VIDEO_VIEWS	Carte de conversation vidéo, vidéo ou GIF requis.	CPV ou coût par vue de 3 s à 100 %
Vues de pré-roll	PREROLL_VIEWS	Vidéo requise.	CPV ou coût par vue de 3 s à 100 %
Clics vers un 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 de site web (mais pas les deux).	CPLC

​

Instruments de financement

Les instruments de financement sont la source du budget d’une campagne. Les instruments de financement ne peuvent pas être créés via l’Ads API ; ils doivent déjà être 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 et GET accounts/:account_id/funding_instruments/:funding_instrument_id pour les détails d’un instrument spécifique.

​

Attributs de l’instrument de financement

Descriptifs : 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 de caractères, au format « %Y-%m-%dT%l:%M:%S%z ».

Statut booléen : paused, deleted et cancelled (true ou false).

Financier : currency (format ISO-4217), credit_limit_local_micro, credit_remaining_local_micro et funded_amount_local_micro. La valeur d’une devise est représentée en micros. Pour l’USD, 5,50 $ est encodé comme 5.50*1e6, soit 5 500 000. Pour représenter une « valeur entière », vous devez multiplier la valeur locale en micros 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 représente credit_limit_local_micro moins le montant déjà dépensé au titre de cet instrument de financement. Il ne représente pas la différence entre funded_amount_local_micro et le montant dépensé. Nous établissons une distinction entre la limite de crédit et le montant financé, car ils correspondent à différentes méthodes de financement sous-jacentes et à différents accords de dépenses conclus avec les annonceurs.

​

Types de moyens de financement

Cartes de crédit

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

Lignes de crédit

Elles prennent la forme d’ordres d’insertion (IO) et sont fixées par les responsables 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. Ce moyen de financement est disponible comme n’importe quel autre. Vous pouvez récupérer les données 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 - Credit Line",
            "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 est son type et le fait qu’il soit disponible pour tous les comptes qui lui 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 concernant les comptes associés à une ligne de crédit spécifique ne sont pas disponibles via l’API (ni via ads.x.com).

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

​

Ciblage

Le ciblage est un concept central de l’Ads API. Le ciblage est défini au niveau de l’élément de campagne, et les options varient selon les emplacements publicitaires. Pour définir de nouveaux critères de ciblage, vous devez utiliser 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 tous les éléments de campagne et GET  accounts/:account_id/line_items/:line_item_id pour récupérer un élément de campagne spécifique.

​

Options de ciblage par emplacement

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

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

• X Search : Ciblage par âge, Appareils, Événements, Sexe, Types de mots-clés (tous), Langue, Lieux, 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, Sexe, Centres d’intérêt, Langue, Lieux, Activation du réseau, Opérateurs réseau, Types de mots-clés non exacts, Types d’audience partenaire, 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, Sexe, Centres d’intérêt, Langue, Lieux, Activation du réseau, Opérateurs réseau, Types de mots-clés non exacts, Types d’audience partenaire, 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 en fonction de tranches d’âge spécifiques. La liste des énumérations de tranches d’âge est disponible sur la page Enumerations.

Événements : Indiquez un événement à cibler. Un seul événement peut être utilisé pour le ciblage (par élément de campagne). Utilisez le 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 cibler tout le monde.

Catégories de boutiques d’applications 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.

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

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

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

Emplacements : Indiquez jusqu’à 2 000 emplacements à cibler. Récupérez la liste via GET targeting_criteria/locations. Il existe des exigences supplémentaires pour les annonces qui ciblent certains pays. Voir Country Targeting and Display Requirements pour plus d’informations.

Mots-clés : Les options de ciblage par mots-clés sont spécifiques au type d’emplacement publicitaire. Vous pouvez utiliser jusqu’à 1 000 mots-clés pour le ciblage (par élément de campagne). Voir la section « Types de mots-clés » pour connaître 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 en fonction de leur opérateur mobile, en utilisant le type de ciblage NETWORK_OPERATOR depuis GET targeting_criteria/network_operators.

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

Plateformes, Versions de plateforme, Appareils et Wifi uniquement : Permettent de cibler les appareils mobiles selon différents axes. Les plateformes constituent un type de ciblage de haut niveau qui peut viser de larges catégories de téléphones. Des valeurs d’exemple sont iOS et Android. Les appareils vous permettent de cibler les utilisateurs de modèles d’appareils mobiles spécifiques, par exemple iPhone 5s, Nexus 4 ou Samsung Galaxy Note. Les versions de plateforme permettent de cibler les utilisateurs de versions spécifiques de systèmes d’exploitation mobiles, jusqu’à la version de correctif. Des exemples incluent iOS 7.1 et Android 4.4. Wifi uniquement vous permet de cibler uniquement les utilisateurs qui utilisent leurs appareils sur un réseau WiFi ; si ce paramètre n’est pas défini, les utilisateurs utilisant la connexion opérateur ainsi que le WiFi 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 les 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 entrer en contact avec eux sur X.

TV Targeting

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

Tweet Engager Retargeting

Le Tweet engager retargeting 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 eux. Avec ce ciblage, les annonceurs peuvent relancer les personnes qui ont vu ou interagi avec le contenu d’un annonceur sur X et qui sont les plus susceptibles d’interagir de nouveau ou de convertir après des messages ou des offres ultérieurs. Les utilisateurs deviennent éligibles au ciblage quelques minutes après 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 Tweet Engager :

• ENGAGEMENT_TYPE, qui accepte soit IMPRESSION, soit ENGAGEMENT comme valeur de ciblage. Cela précise si vous souhaitez cibler des utilisateurs exposés (IMPRESSION) ou des utilisateurs engagés (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 (en fonction de ENGAGEMENT_TYPE) sont ceux qui seront ciblés.
• USER_ENGAGEMENT, qui utilise l’id d’utilisateur promu comme valeur de ciblage pour cibler les utilisateurs qui ont été exposés au contenu organique d’un annonceur ou qui ont interagi avec celui‑ci (en fonction de ENGAGEMENT_TYPE). Il doit s’agir de l’id d’utilisateur promu associé au compte Ads.

Remarque : ENGAGEMENT_TYPE est requis en plus d’au moins une valeur CAMPAIGN_ENGAGEMENT ou USER_ENGAGEMENT valide. Les deux types de ciblage Tweet engager peuvent être présents et plusieurs campagnes peuvent être ciblées sur un même line item.

Video Viewer Targeting : le ciblage Video viewer s’appuie sur le ciblage Tweet engager pour permettre aux annonceurs de cibler les audiences qui ont 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 line items avec objectif de vues de vidéo.

Types de ciblage Video Viewer :

• 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 Tweet engager, un ou les deux éléments suivants doivent également être présents dans les critères de ciblage du line item lorsque ENGAGEMENT_TYPE est utilisé :

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

Keyword Types

Consultez notre document d’aide sur le keyword targeting pour une vue d’ensemble conceptuelle.

• Broad (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 (par exemple, « car repair » correspondra également à « automobile fix »). Si vous souhaitez cibler sans extension, vous devez ajouter un signe + devant les mots‑clés, comme « +boat +jet ». L’utilisation de mots‑clés sans le + correspond par défaut à Broad Match.
• Unordered (obsolète) : fait correspondre tous les mots, indépendamment de l’ordre. Insensible à la casse, aux pluriels ou au temps.
• Phrase : fait correspondre exactement la chaîne de mots‑clés, d’autres mots‑clés peuvent être présents.
• Exact : fait correspondre exactement la chaîne de mots‑clés, et aucune autre.
• Negative : évite de faire correspondre les recherches qui incluent tous ces mots‑clés quelque part dans la requête, quel que soit l’ordre dans lequel ils sont écrits, même si d’autres mots sont présents.
• Negative Phrase : évite de faire correspondre les recherches qui incluent exactement cette chaîne de mots‑clés quelque part dans la requête, même si d’autres mots sont présents.
• Negative Exact : é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 au moyen du ciblage par mots-clés. Pour utiliser le ciblage par emoji, créez simplement un ciblage par mots-clés pour les 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 consultés dans la liste twemoji. Le ciblage d’un emoji applique le ciblage à toutes ses variantes.

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

​

Combinaisons de critères de ciblage

Workflow de campagne mis à jour

Créez des campagnes avec un ciblage large basé sur des 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 de ciblage supplémentaires (par exemple 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 campagne, l’élément de campagne 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 de la façon suivante :

• Les types de ciblage « principaux » seront combinés par ∪ (c.-à-d. placés dans 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 diffuse en ciblant :

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

Les critères de ciblage seront :

[US OR GB OR CA] AND [Female] AND [Audiences personnalisées ∪ Mots-clés]

​

Exemples supplémentaires

• Sélectionnez le genre et la zone géographique mais aucun critère principal : (Homme) ET (US OU GB)
• Sélectionnez le genre, la zone géographique, les centres d’intérêt : (Femme) ET (CA) ET (Informatique OU Technologie OU Startups)
• Sélectionnez le genre, la zone géographique, les centres d’intérêt, les Tailored Audiences et les mots-clés : (Homme) ET (GB) ET (Voitures ∪ Tailored Audiences for CRM ∪ autocross)

​

Rythme de dépense 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 Tweets sponsorisés et de Comptes sponsorisés. L’activation de la diffusion standard, qui est 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 se produire assez tôt dans la journée selon le ciblage et la concurrence. Cela s’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 de campagne aussi rapidement que possible, définissez le paramètre standard_delivery sur false afin de passer à un rythme de diffusion accéléré (voir GET accounts/:account_id/campaigns).

Remarques

• Le « jour » est défini par le fuseau horaire du compte annonceur X (par exemple America/Los_Angeles).
• Les premiers résultats indiquent que la diffusion standard améliore le 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 le rythme de dépense, veuillez consulter la page FAQ sur les enchères et les offres.

​

Enchères ciblées

Gestion de campagnes

​

Stratégie d’enchère

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

Toutes les anciennes combinaisons de paramètres (marquées comme obsolètes) peuvent être reproduites en définissant un paramètre goal équivalent. Vous trouverez plus d’informations dans l’annonce ici.

Par exemple :

Objectif de la campagne	Ancien comportement	Ads API v10+
App Installs	bid_type= AUTO bid_unit = APP_INSTALLS charge_by = APP_CLICKS	goal = APP_INSTALLS bid_strategy = AUTO
Website Clicks	bid_type = TARGET (Remarque : bid_unit n’était pas requis pour certains objectifs de campagne)	bid_strategy = TARGET

​

Enchères cibles

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

Cette fonctionnalité vous donne la flexibilité d’atteindre les utilisateurs particulièrement susceptibles d’effectuer l’action souhaitée (comme un clic sur un lien, un lead ou un abonnement) tout en gardant le contrôle de vos coûts. Il s’agit d’une fonctionnalité puissante pour les annonceurs qui souhaitent davantage d’options pour la configuration et l’optimisation de leurs campagnes (y compris les options d’enchères).

Pour les line items avec des objectifs de campagne compatibles, nous avons introduit un nouveau mécanisme de tarification du montant de l’enchère qui vous permet de définir un coût cible que vous souhaitez payer. Notre plateforme publicitaire enchérit dynamiquement en votre nom pour vous aider à générer davantage de résultats, tout en s’efforçant de maintenir votre coût moyen dans une fourchette de 20 % autour de la cible que vous avez spécifiée. Le paramètre bid_strategy sur les line items peut être défini sur la valeur TARGET pour activer les enchères cibles 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 de ciblage et d’affichage propres à chaque pays sont présenté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 à vos utilisateurs :

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

​

Instruments de financement gérés par le partenaire

Le flux d’onboarding configure un compte ads.x.com pour le compte X, que le partenaire peut gérer via l’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 Ads API PMFI peut prendre jusqu’à 3 semaines à partir 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 lors du processus d’intégration.
• Le app_id ou le consumer_secret pour l’App X qui sera utilisée pour l’accès à l’Ads API. Vous pouvez afficher et modifier vos Apps X 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 App X, vous devrez disposer d’un compte développeur approuvé. X autorise une app pour la production + sandbox et une app facultative pour un accès sandbox uniquement. L’App X doit être créée sur un handle X d’entreprise contrôlé par le partenaire.  

​

Parcours d’onboarding de l’annonceur

Le parcours d’onboarding de l’annonceur se déroule via un navigateur web de la manière suivante :

1. L’utilisateur démarre le parcours d’onboarding sur le site web 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’app_id API du partenaire, le user_id X du handle X à intégrer, ainsi qu’une URL de rappel et d’autres champs documentés ci‑dessous.
3. Il est demandé à l’utilisateur de se connecter à ads.x.com en utilisant la page de connexion standard de x.com.
4. Une fois l’utilisateur connecté, le processus d’onboarding est lancé. Cette étape inclut l’examen des annonces, la validation du compte et d’autres vérifications.
5. Lorsque toutes les tâches d’onboarding sont terminées, l’utilisateur est redirigé vers l’URL de rappel fournie par le partenaire Ads API, avec une charge utile qui indique la réussite ou l’échec. Cela inclut le processus d’autorisation en 3 étapes.  

​

Charge utile de redirection d’intégration

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	URL encoded string	l’utilisateur sera redirigé vers cette URL après la fin du processus de liaison de compte, quel qu’en soit le résultat. Voir la section sur l’URL de redirection du partenaire pour les détails du protocole
client_app_id	integer	id d’App client X API, utilisé pour identifier le partenaire gestionnaire
promotable_user_id	integer	X user_id du @handle dont les promotions doivent être gérées par le partenaire gestionnaire. Utilisé pour s’assurer qu’il s’agit du même utilisateur que celui qui se connecte à ads.x.com pour terminer le processus de liaison
fi_description	URL encoded String (max 255 characters)	nom de l’instrument de financement. Celui-ci sera affiché dans le champ de description dans l’API lorsque l’instrument de financement est récupéré. Si une description funding_instrument est fournie, l’instrument de financement existant sera mis en pause et un nouvel instrument de financement partenaire géré sera configuré (s’il en existe déjà un avec le même nom, rien ne se passera).
timezone	String, in Area/Location format	ce fuseau horaire sera utilisé pour déterminer le jour auquel les budgets journaliers s’appliquent et dans lequel les frais seront agrégés
currency	ISO 4217 Currency Code	devise qui sera utilisée pour saisir les offres et dans laquelle les frais seront facturés
country	ISO 3166-1 alpha 2 Country Code	pays de facturation pour le compte
signature	URL encoded, base64 encoded binary code, as explained below	signature qui combine 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 à l’aide du paramètre callback_url dans la requête de lien de compte (voir ci‑dessus). Les paramètres ajoutés par ads.x.com sont :

Nom	Type	Description
status	string	OK un compte a été créé ou un compte existant et éligible 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 est différent du promotable_user_id dans la requête de lien 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 du compte publicitaire X associé
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 lien de compte est destiné, le X user_id doit être concaténé au secret partagé (en utilisant &) 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 lien de compte est destiné, le X user_id doit être concaténé au secret partagé (en utilisant &) lors de la signature de la requête.  

​

Signature de la requête et des URL de rappel

Afin de s’assurer que les requêtes vers /link_managed_account et l’URL de rappel sont valides, les requêtes doivent être signées à la source et vérifiées par le destinataire avant que celui‑ci n’agisse en conséquence. Signer la requête avec 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 la signature est similaire à celui utilisé par OAuth.

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

• Convertissez la méthode HTTP en majuscules et définissez la chaîne de base égale à cette valeur.
• Ajoutez le caractère « & » à la chaîne de base.
• Encodez en pourcentage 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 qui sera signée.
• Triez la liste des paramètres par ordre alphabétique selon la clé.
• 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 utilisant 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 nouvelle ligne final, encodez en pourcentage la signature générée à l’étape 3 et ajoutez‑la à l’URL dans un paramètre de 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 pourcent 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

En utilisant l’algorithme hmac-sha1, nous allons signer cette chaîne 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 pourcent) à la fin de l’URL d’origine dans le paramètre 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 du partenaire (rappel 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 pourcent 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

En utilisant l’algorithme hmac-sha1, nous allons signer cette chaîne avec le mot « secret » et l’id de l’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, après 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 la clé partagée

L’algorithme de signature doit pouvoir être réutilisé avec plusieurs clés. Cela permet d’utiliser plusieurs clés partagées et de procéder à leur rotation périodique.  

​

Création de partner_managed_funding_instrument

Si le paramètre fi_description est fourni et qu’aucun partner_managed_funding_instrument existant 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éé.  

​

Appels répétés du flux d’onboarding / actualisation du jeton

Le flux d’onboarding peut être relancé si le jeton d’accès à l’API a été perdu. L’implémentation du flux d’onboarding nécessitera 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 initier le flux OAuth pour obtenir un jeton d’accès.  

​

Flux d’erreur sans redirection

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 sera présentée à l’utilisateur.  

​

Mises à jour en continu du PMFI

Une fois que l’annonceur a été intégré, l’instrument de financement peut être géré via le point de terminaison PUT accounts/:account_id/funding_instruments/:funding_instrument_id uniquement par le partenaire qui le gère.

​

Emplacements

Les publicités X peuvent être diffusées à plusieurs emplacements. Cela se configure 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

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

Par ailleurs, le tableau suivant répertorie les combinaisons valides d’emplacement et d’objectif.

Objectif	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 comporter ALL_ON_TWITTER, n’importe quelle combinaison d’emplacements qui inclut TWITTER_TIMELINE, ou TWITTER_TIMELINE seul.

​

FAQ sur les groupes d’annonces

Ce document regroupe une série de questions fréquemment posées au sujet des groupes d’annonces dans l’API Ads de X.

​

Qu’est-ce qu’un Ad Group ?

Les Ad Groups, appelés line items dans l’Ads API, sont rattachés aux campagnes et sont utilisés pour le ciblage et les enchères auprès d’un ensemble d’utilisateurs de X. Les annonceurs font la promotion de Tweets ou de 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 de publicités ?

Les groupes de publicités sont créés en appelant POST accounts/:account_id/line_items plusieurs fois pour le même id de campagne, en conservant pour chaque élément de campagne son propre ciblage (éventuellement complètement différent) et les Tweets qui y sont associés. La limite est de 100 éléments de campagne par campagne et de 200 campagnes actives pour un même compte publicitaire. Pour l’ensemble des campagnes, la limite est de 8 000 éléments de campagne actifs par compte publicitaire.

​

Pourquoi devrions-nous ajouter la prise en charge des Ad Groups ?

Les Ad Groups sont conçus pour faciliter l’organisation, l’optimisation et la gestion des campagnes pour les annonceurs.

L’avantage des Ad Groups est de permettre de comparer et de contrôler différentes stratégies en matière d’enchères, de budget, de créations publicitaires et de ciblage. Lorsque plusieurs Tweets sponsorisés sont associés à un seul line item, le système d’enchères sélectionne le meilleur Tweet de ce groupe, puis sélectionne le meilleur Tweet pour cette campagne parmi tous les line items. Si vous avez plusieurs Ad Groups contenant chacun un seul Tweet, cela revient à sélectionner, pour chaque Ad Group, le Tweet qui a le plus de chances de mieux performer.

L’utilisation des Ad Groups permet à un annonceur de répartir le ciblage et les enchères en un nombre beaucoup plus élevé de combinaisons possibles et, de manière générale, de segmenter le ciblage en groupes logiques.

Les outils Ads API, en particulier, peuvent être conçus autour de règles d’optimisation très fines basées sur les Ad Groups, ce qui serait plus difficile à réaliser via des modifications manuelles en raison du grand nombre de combinaisons de line items et de créations.

​

Quel est le lien entre le budget de l’élément de campagne (line item) et le budget de la campagne dans une campagne Ad Groups ?

La valeur de total_budget_amount_local_micro pour un élément de campagne ne peut pas dépasser le budget total de sa campagne parente. De même, la valeur de bid_amount_local_micro de l’élément de campagne 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 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 campagne enfants, et que la répartition du budget entre les éléments de campagne dépend en partie de l’outil Ads API, chargé de l’optimiser et de l’ajuster efficacement, car les performances quotidiennes du ciblage (élément de campagne) peuvent varier sensiblement 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 qu’un seul élément de campagne ?

Les performances d’une campagne dépendent de nombreux facteurs et, en fin de compte, le Tweet est le facteur décisif en matière de performance. Un élément de campagne est considéré comme un facteur déterminant pour savoir si un Tweet est même en lice pour être diffusé à un utilisateur.

Les éléments de campagne qui ciblent les mêmes ensembles d’utilisateurs sont considérés comme ayant un chevauchement d’audience. Il est recommandé, comme bonne pratique, de réduire ce chevauchement de ciblage entre les éléments de campagne afin que les ensembles d’utilisateurs les plus performants puissent être clairement identifiés.

​

Guides

​

Objectif de vues pour les pré-roll vidéo

Le guide suivant décrit les étapes nécessaires pour configurer une campagne PREROLL_VIEWS sur l’API Ads. De manière générale, ces campagnes sont réparties en deux types : « Curated Categories » et « Content Categories » (appelées « Standard Categories » dans l’interface utilisateur Ads).  

​

Points de terminaison requis

• Chunked media upload (pour le téléversement de vidéos)
• POST accounts/:account_id/media_library (pour l’association de 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 de publicités)
• POST accounts/:account_id/media_creatives (pour associer la vidéo au groupe de publicités)
• POST accounts/:account_id/preroll_call_to_action (pour définir l’appel à l’action (CTA) et l’URL de redirection)
• POST batch/accounts/:account_id/targeting_criteria (ciblage)

​

Étapes

​

Téléverser la vidéo

Le téléversement de la vidéo comporte 2 étapes :

​

Importer le média vidéo

Tout d’abord, à l’aide de l’endpoint Chunked media upload, vous allez téléverser la vidéo sur X pour traitement. Vous devez transmettre media_category=amplify_video lors de l’appel initial INIT en utilisant cet endpoint. Vous téléverserez la vidéo en plusieurs segments. Une fois que la réponse STATUS renvoie un state égal à succeeded, vous pouvez poursuivre avec les étapes suivantes. Vous trouverez davantage d’informations sur le téléversement de médias avec l’endpoint segmenté dans notre page Présentation de la vidéo sponsorisée.

​

Ajouter la vidéo au compte publicitaire

Une fois que l’état renvoyé par la commande STATUS est succeeded, vous utiliserez le media_key renvoyé par cet endpoint pour ajouter la vidéo à la bibliothèque de médias de l’annonceur, en utilisant 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 le line item/groupe d’annonces. Les line items doivent être créés avec l’objective VIDEO_VIEWS_PREROLL et le product_type MEDIA. Le paramètre categories doit également être renseigné avec 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 de line item

Les line items doivent avoir le paramètre categories défini sur l’ensemble approprié de catégories IAB, récupérées via l’endpoint GET content_categories. Chacune de ces catégories 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 de iab_categories renvoyé dans la réponse, afin de définir le paramètre categories sur l’endpoint des line items. Toute application partielle de iab_categories entraînera l’application de l’ensemble du groupe au line item. 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": "Voyages",
      "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": "Organismes à but non lucratif",
      "iab_categories": \[
        "IAB11-1",
        "IAB11-2",
        "IAB11-3",
        "IAB11-5"
      \]
    }
  \]
}

Maintenant, afin de définir le paramètre categories sur la valeur “Science & Education”, l’ensemble des iab_categories, c’est‑à‑dire "IAB5", "IAB15", doit être défini 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 de l’éditeur

Un annonceur peut choisir de cibler soit une catégorie de contenu, soit une catégorie organisée, avec des informations supplémentaires décrites ci‑dessous. 

Remarque : Les éléments de campagne peuvent cibler soit des catégories organisées, soit 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 propres à chaque pays et nécessitent donc que le line item cible le pays approprié en fonction du country_code de la catégorie.

Pour utiliser l’une de ces catégories, les étapes suivantes doivent être effectuées dans l’ordre indiqué :

1. Le line item 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 le line item à un curated_category_id spécifique. 

Remarque : Associer un line item à une catégorie sélectionnée limite également à 5 le nombre d’éditeurs pouvant être ajoutés à la denylist. La liste complète des user_id utilisés pour placer certains éditeurs sur la denylist peut être récupérée depuis l’endpoint GET publishers. De plus, un line item 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, qui n’est disponible qu’aux États-Unis, avec le line item créé à l’étape précédente.

Tout d’abord, les critères de ciblage du line item sont définis sur la valeur 96683cc9126741d

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

{
  "data": \[
    {
      "name": "United States",
      "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": "United States",
      "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 à partir de l’endpoint GET curated_categories. Ces catégories peuvent ensuite être ciblées par le line item à l’aide des endpoints de critères de ciblage par lot. L’exemple suivant illustre comment sélectionner une catégorie de contenu spécifique, id: sr, qui correspond à « Actualités et événements récents », et l’appliquer au line item.

Remarque : L’ensemble des iab_categories dans la réponse GET curated_categories doit être ciblé via l’endpoint de critères de ciblage. Dans le cas contraire, une erreur de validation sera renvoyée. 

GET https://ads-api.x.com/8/content_categories
{
      "name": "News & Current Events",
      "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": "News",
      "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": "Society",
      "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 campagne

Utilisez le point de terminaison 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 l’appel à l’action (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. À la place, le créatif vidéo est associé à votre groupe d’annonces (line item) et les informations de CTA sont associées à une entité preroll_call_to_action. L’endpoint POST accounts/:account_id/preroll_call_to_action vous permet de contrôler 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":"WATCH_NOW",
   "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":"VISIT_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 pré-roll n’est disponible qu’en utilisant 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 que la publicité soit associée à un ensemble d’utilisateurs. Indiquez le user_id X ou le publisher_user_id correspondant aux comptes à exclure.

L’endpoint GET publishers peut être utilisé pour récupérer la liste des user_id à exclure pour les catégories de contenu (Content Categories). Le publisher_user_id retourné 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 (Curated Categories).

Remarque : Un maximum de 5 publisher_user_id peuvent être exclus pour les catégories organisées (Curated Categories) et 50 user_id pour les catégories de contenu (Content Categories).

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 en utilisant 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
  }
}

​

Analytics

Les statistiques des campagnes VIDEO_VIEWS_PREROLL sont disponibles via nos points de terminaison de statistiques.

​

Ciblage par mots-clés dans les fils

Le ciblage par mots-clés est fondamental pour nos produits de Tweets sponsorisés, en améliorant la portée des campagnes. Le ciblage par mots-clés dans les fils 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 disant « I’m starting to plan my trip to Cabo, any suggestions? » pendant que la campagne est active, cet utilisateur pourra voir peu de temps après le Tweet sponsorisé de l’annonceur.

​

Comment ça fonctionne ?

En bref : d’un point de vue API, ce changement est assez simple : vous pouvez désormais cibler des mots-clés pour les Tweets sponsorisés dans la Timeline. Il suffit de définir targeting_type sur unordered_keywords ou phrase_keywords pour les line items (éléments de campagne).

​

Guide de démarrage rapide

• Créez un nouvel élément de campagne dont le placement inclut soit ALL_ON_TWITTER soit TWITTER_TIMELINE. POST accounts/:account_id/line_items
• Créez les critères de ciblage pour ce nouvel élément de campagne en utilisant BROAD_KEYWORD et en définissant la ou les valeurs de votre mot-clé. 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 campagne pour mesurer ses performances. GET stats/accounts/:account_id

​

Référence de l’API

​

Comptes

Lancer dans Postman

​

GET accounts

Récupérer les détails de certains ou de tous les comptes pour lesquels la publicité est activée et 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 à 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
q optional	Une requête facultative pour restreindre la ressource par name. Note: cette opération 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, dans l’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 l’un de l’autre. Note: les requêtes qui incluent total_count auront des limites de taux plus faibles, actuellement définies à 200 par 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ère 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	Identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’Advertiser API, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
with_deleted optional	Inclure les résultats supprimés dans votre requête. Type : boolean Valeur par défaut : false Valeurs possibles : true, false

Exemple de requête

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 : ENVIRONNEMENT SANDBOX UNIQUEMENT

Créez un compte publicitaire dans l’environnement sandbox.

URL de la 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": "Sandbox account",
             "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

Nom	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’Advertiser API, à 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é auquel le compte est associé. 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

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

Requête d’exemple

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

Réponse d’exemple

       {
         "data": {
           "name": "Sandbox account",
           "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": "ACCEPTED",
           "deleted": true
         },
         "request": {
           "params": {
             "account_id": "gq12fh"
           }
         }
       }

​

Apps du compte

Exécuter dans Postman ❯

​

GET account_apps

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

Resource URL

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

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 à récupérer par requête distincte. Type: int Valeur par défaut : 200 Min., max. : 1, 1000
cursor optional	Spécifie un curseur pour obtenir la page de résultats suivante. Voir Pagination 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	Inclure les résultats supprimés dans votre requête. Type: boolean Valeur par défaut : false Valeurs possibles : 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 basses, actuellement fixées à 200 toutes les 15 minutes. Type: boolean Valeur par défaut : false Valeurs possibles : true, false

Example Request

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

Example Response

       {
         "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érer 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 ajout à une liste d’autorisation (allowlisting).

URL de la ressource

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

Paramètres

Nom	Description
account_id required	L’identifiant du compte utilisé. Type : string Exemple : 18ce54d4x5t
count optional	Spécifie le nombre d’enregistrements à tenter de récupérer par requête distincte. Type : int Valeur par défaut : 200 Min, Max : 1, 1000
cursor optional	Spécifie un curseur pour obtenir la page de résultats suivante. Voir Pagination pour plus d’informations. Type : string Exemple : 8x7v00oow
entity_type required	Le type d’entité pour lequel récupérer les données. Type : enum Exemple : PROMOTED_TWEET Valeurs possibles : 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 Exemple : 8u94t
start_time required	Limite les données récupérées à l’heure de début spécifiée, exprimée au format ISO 8601. Remarque : Doit être exprimée en heures entières (0 minute et 0 seconde). Type : string Exemple : 2017-05-19T07:00:00Z
end_time required	Limite les données récupérées à l’heure de fin spécifiée, exprimée au format ISO 8601. Remarque : Doit être exprimée en heures entières (0 minute et 0 seconde). Type : string Exemple : 2017-05-26T07:00:00Z
user_id optional	Limite la réponse à un utilisateur spécifique. Type : long Exemple : 3271358660

Exemple de requête

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

Exemple de réponse

    {
      "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": "test_campaign",
            "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

Récupérez les categories d’activité commerciales valides pour les groupes de publicités (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 de publicités avec l’objectif PREROLL_VIEWS, une ou deux advertiser_business_categories doivent être définies pour ce groupe. Cela peut être fait en définissant, pour le paramètre de requête categories de l’endpoint line item, l’ensemble des iab_categories correspondantes disponibles via cet endpoint.

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

URL de la ressource

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

Paramètres

Aucun paramètre de requête

Exemple de requête

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

Exemple de réponse

{
      "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": "Voyages",
          "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": "Organisations à 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éterminer la taille approximative de l’audience de vos campagnes.

Ce point de terminaison 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 obligatoires et facultatifs est disponible sur le point de terminaison POST accounts/:account_id/targeting_criteria. Les requêtes doivent être des requêtes 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 principal ; vous pouvez consulter la liste de tous les critères de ciblage principaux sur notre page de ciblage des campagnes.

URL de la ressource

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

Paramètres

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 Advertiser API à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
targeting_criteria required	Objet JSON contenant tous les paramètres des objets de critères de ciblage. Une liste des paramètres de critères de ciblage obligatoires et facultatifs est disponible sur le point de terminaison 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 Valeur par défaut : EQ

Exemple de requête

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 de l’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) en lien avec le compte publicitaire spécifié. Ces autorisations correspondent à celles exposées sur ads.x.com.

Les valeurs possibles incluent :

• 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 ne peut pas ajouter ou supprimer des utilisateurs ni modifier les paramètres
• CREATIVE_MANAGER : Accès pour modifier les créations publicitaires 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 informations sur l’audience, mais aucun accès pour créer, modifier ou afficher des campagnes
• PARTNER_AUDIENCE_MANAGER : Accès réservé à l’API pour consulter et modifier les audiences des partenaires de données, mais aucun accès aux campagnes, créations ou autres types d’audiences.

De plus, l’autorisation TWEET_COMPOSER indique que l’utilisateur authentifié peut créer des Tweets nullcastés (ou « Promoted-only ») au nom de l’annonceur. Ceci n’est disponible que pour les utilisateurs disposant des 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ères

Exécuter dans Postman

​

GET bidding_rules

Récupérer les règles d’enchères pour certaines devises ou pour toutes. La réponse indiquera les enchères CPE (coût par interaction) minimales et maximales.

Bien que ces règles d’enchères changent rarement, il est recommandé que vos systèmes rafraîchissent ces endpoints au moins une fois par mois.

URL de la ressource

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

Paramètres

Nom	Description
currency optional	Type de devise utilisé pour filtrer les résultats, identifié à l’aide de 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 associées à l’utilisateur authentifié. Type: string Exemple: USD

Exemple de requête

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

Exemple de réponse

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

Lancer dans Postman

​

GET accounts/:account_id/campaigns

Récupère les détails de certaines ou de toutes les campagnes associées au compte actuel.

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 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
campaign_ids optional	Limite la réponse uniquement aux campagnes souhaitées en spécifiant une liste d’identifiants séparés par des virgules. Jusqu’à 200 IDs peuvent être fournis. Type: string Exemple: 8wku2
count optional	Spécifie le nombre d’enregistrements à tenter de récupérer par requête distincte. Type: int Valeur par défaut: 200 Min, Max: 1, 1000
cursor optional	Spécifie un curseur pour obtenir la page de résultats suivante. Voir Pagination pour plus d’informations. Type: string Exemple: 8x7v00oow
funding_instrument_ids optional	Limite la réponse uniquement aux campagnes sous des instruments de financement spécifiques en spécifiant une liste d’identifiants séparés par des virgules. Jusqu’à 200 IDs peuvent être fournis. Type: string Exemple: lygyi
q optional	Requête optionnelle pour restreindre les ressources par name. Type: string Longueur min, max: 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 Exemple: created_at-asc
with_deleted optional	Inclut les résultats supprimés dans votre requête. Type: boolean Valeur par défaut: false Valeurs possibles: true, false
with_draft optional	Inclut les résultats des campagnes à l’état de brouillon dans votre requête. Type: boolean Valeur par défaut: false Valeurs possibles: true, false
with_total_count optional	Inclut l’attribut de réponse total_count. Remarque : ce paramètre et cursor sont exclusifs. Remarque : les requêtes qui incluent total_count auront des limites de taux plus faibles, actuellement définies à 200 toutes les 15 minutes. Type: boolean Valeur par défaut: false Valeurs possibles: 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érer 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

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

Exemple de requête

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",
        "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
      }
    }

​

POST accounts/:account_id/campaigns

Crée une nouvelle campagne associée au compte courant.

Remarque : il existe une limite par défaut de 200 campagnes actives par compte. Cependant, il n’y a aucune limite pour le nombre de campagnes inactives. Cette limite peut être portée à 8 000 campagnes actives. Pour activer cette limite plus élevée, 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 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
funding_instrument_id required	L’identifiant de l’instrument de financement sous lequel créer la campagne. Type : string Exemple : lygyi
name required	Le nom de la campagne. Longueur maximale : 255 caractères. Type : string Exemple : demo
budget_optimization optional	Type d’optimisation du budget à appliquer. Type : enum Valeur par défaut : CAMPAIGN Valeurs possibles : CAMPAIGN, LINE_ITEM
daily_budget_amount_local_micro sometimes required	Le montant du budget quotidien à allouer à la campagne. La devise associée à l’instrument de financement spécifié est utilisée. Pour l’USD, 5,50 $ est représenté par 5500000. Remarque : cette valeur doit être inférieure ou égale à total_budget_amount_local_micro et est requise pour la plupart des types d’instruments de financement. Type : long Exemple : 5500000
entity_status optional	Le statut de la campagne. Type : enum Valeur par défaut : ACTIVE Valeurs possibles : ACTIVE, DRAFT, PAUSED
purchase_order_number optional	Le numéro de référence de réservation. Utilisez ce champ pour faciliter le rapprochement des factures. Longueur maximale : 50 caractères. Type : string Exemple : D00805843
standard_delivery optional	Active la diffusion standard ou accélérée. Voir Budget Pacing 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 CAMPAIGN. Type : boolean Valeur par défaut : true Valeurs possibles : true, false
total_budget_amount_local_micro optional	Le montant total du budget à allouer à la campagne. La devise associée à l’instrument de financement spécifié est 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 la création en lot de nouvelles campagnes avec 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, qu’il s’agisse d’erreur ou de succès, préservent l’ordre des éléments de la requête initiale.

Réponses par lot

Les réponses de l’API par lot renvoient une collection ordonnée d’éléments. Pour le reste, elles sont identiques en structure à leurs endpoints équivalents pour un seul élément.

Erreurs par lot

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

Resource URL

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

Parameters

Name	Description
operation_type required	Le type d’opération par élément en cours d’exécution. Type: enum Valeurs possibles : Create, Delete, Update
params required	Un objet JSON contenant tous les paramètres pour les objets de campagne. Pour une liste des paramètres de campagne obligatoires et optionnels, voir ici.

Example Request

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

    [
      {
        "operation_type":"Create",
        "params":{
          "name":"batch campaigns",
          "funding_instrument_id":"lygyi",
          "daily_budget_amount_local_micro":140000000,
          "entity_status":"PAUSED",
          "budget_optimization":"CAMPAIGN"
        }
      }
    ]

Exemple de réponse

    {
      "data": [
        {
          "name": "batch campaigns",
          "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": "8yn7m",
          "entity_status": "PAUSED",
          "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 actuel.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/campaigns/:campaign_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
campaign_id required	Une référence à la campagne concernée par la requête. Type : string Exemple : 8wku2
budget_optimization optional	Sélectionne le type d’optimisation du budget à appliquer. Type : enum Valeur par défaut : CAMPAIGN Valeurs possibles : CAMPAIGN, LINE_ITEM
daily_budget_amount_local_micro optional	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. Lorsque ce champ n’est pas fourni, la campagne dépense de manière uniforme en fonction du budget total et sur toute la durée de la période de diffusion de la campagne. Remarque : ce montant doit être inférieur ou égal à total_budget_amount_local_micro. Type : long Exemple : 5500000
entity_status optional	Le statut de la campagne. Type : enum Valeurs possibles : ACTIVE, PAUSED
name optional	Le nom de la campagne. Longueur maximale : 255 caractères. Type : string Exemple : demo
purchase_order_number optional	Le numéro de référence de réservation. Utilisez ce champ pour faciliter le rapprochement des factures. Longueur maximale : 50 caractères. Type : string Exemple : D00805843
standard_delivery optional	Active la diffusion standard ou accélérée. Voir Budget Pacing 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 CAMPAIGN. Type : boolean Valeur par défaut : true Valeurs possibles : true, false
total_budget_amount_local_micro optional	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 : 140000000

Example Request

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

Example Response

    {
      "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 suppression de la ressource renverra un code d’état HTTP 404.

URL de la ressource

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

Paramètres

Nom	Description
account_id required	L’identifiant du compte utilisé. Il apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
campaign_id required	Une référence à la campagne concerné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 line item.

Chaque content_category correspond à une ou plusieurs catégories IAB. Pour ce faire, définissez targeting_type sur IAB_CATEGORY sur le endpoint batch targeting_critera afin d’inclure l’ensemble des iab_categories correspondantes renvoyées par la requête content_categories. Le non‑respect de cette étape entraînera une erreur de validation.

Les informations éditeur pour chacune de ces catégories de contenu peuvent être récupérées via le endpoint GET publishers.

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

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": "Automotive (Cars, Trucks, Racing)",
          "id": "ru",
          "iab_categories": [
            "IAB2"
          ],
          "publishers_in_last_thirty_days": 12,
          "videos_monetized_in_last_thirty_days": 316
        },
        {
          "name": "Comedy",
          "id": "sk",
          "iab_categories": [
            "IAB1-4"
          ],
          "publishers_in_last_thirty_days": 19,
          "videos_monetized_in_last_thirty_days": 174
        },
        {
          "name": "Digital Creators",
          "id": "sl",
          "iab_categories": [
            "IAB25-1"
          ],
          "publishers_in_last_thirty_days": 110,
          "videos_monetized_in_last_thirty_days": 1257
        },
        {
          "name": "Entertainment & Pop Culture",
          "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": "Financial & Business News",
          "id": "sn",
          "iab_categories": [
            "IAB3",
            "IAB13",
            "IAB21"
          ],
          "publishers_in_last_thirty_days": 29,
          "videos_monetized_in_last_thirty_days": 1461
        },
        {
          "name": "Food & Drink",
          "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": "Style de vie (Mode, Voyages, 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": "Music",
          "id": "sq",
          "iab_categories": [
            "IAB1-6"
          ],
          "publishers_in_last_thirty_days": 31,
          "videos_monetized_in_last_thirty_days": 518
        },
        {
          "name": "News & Current Events",
          "id": "sr",
          "iab_categories": [
            "IAB12",
            "IAB14"
          ],
          "publishers_in_last_thirty_days": 125,
          "videos_monetized_in_last_thirty_days": 5507
        },
        {
          "name": "Politics",
          "id": "s4",
          "iab_categories": [
            "IAB11"
          ],
          "publishers_in_last_thirty_days": 19,
          "videos_monetized_in_last_thirty_days": 1402
        },
        {
          "name": "Science & Education",
          "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": "Technology",
          "id": "sg",
          "iab_categories": [
            "IAB19"
          ],
          "publishers_in_last_thirty_days": 13,
          "videos_monetized_in_last_thirty_days": 1089
        },
        {
          "name": "Television",
          "id": "sh",
          "iab_categories": [
            "IAB1-7"
          ],
          "publishers_in_last_thirty_days": 58,
          "videos_monetized_in_last_thirty_days": 1307
        },
        {
          "name": "Esports & Video Games",
          "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érer une liste de 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 sur l’objectif Video Views Pre-roll.

URL de la ressource

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

Paramètres

Name	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes Advertiser API, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
country_codes required	Limite la réponse aux seuls pays souhaités en spécifiant une liste, séparée par des virgules, de codes pays ISO à deux lettres. Jusqu’à 200 codes peuvent être fournis. Type : string Exemple : US
cursor optional	Spécifie un curseur pour obtenir la page suivante de résultats. Voir Pagination pour plus d’informations. Type : string Exemple : 8x7v00oow

Exemple de requête

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

Exemple de réponse

{
      "request": {
        "params": {
          "country_codes": [
            "US"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "name": "Basketball",
          "description": "Diffusez à côté du meilleur contenu basketball quotidien, incluant les équipes universitaires, les équipes professionnelles et les principaux comptes médias sportifs partageant des vidéos de basketball 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 gaming",
          "description": "Run next to the best of everyday gaming content exclusively from a list of some of online gaming’s biggest and most loved digital creators.",
          "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": "Baseball",
          "description": "Diffusez à côté du meilleur contenu baseball quotidien, incluant les équipes universitaires, les équipes professionnelles et les principaux comptes médias sportifs partageant une couverture majeure du baseball.",
          "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 esports",
          "description": "Run next to the programming from the world’s best esports teams, covering both in-event coverage and other year-round complimentary programming.",
          "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 américain ",
          "description": "Diffusez aux côtés du meilleur contenu quotidien de football américain, incluant les équipes universitaires, les équipes professionnelles et les principaux comptes 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 style de vie masculins",
          "description": "Diffusez aux côtés de contenu provenant d'un ensemble de comptes sélectionnés en fonction des profils de leurs abonnés pour vous aider à atteindre une audience majoritairement masculine, incluant certains des principaux comptes partageant du contenu technologique, d'actualités et de style de vie.",
          "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 style de vie féminins",
          "description": "Diffusez aux côtés de contenu provenant d'un ensemble de comptes sélectionnés en fonction des profils de leurs abonnés pour vous aider à atteindre une audience majoritairement féminine, incluant certains des principaux comptes partageant du contenu de culture populaire, d'actualités et de style de vie.",
          "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 et positif",
          "description": "Diffusez aux côtés d'une liste de comptes sélectionnés pour le volume de contenu positif et de conversations agréables qu'ils ont constamment générés 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": "Football",
          "description": "Diffusez aux côtés du meilleur contenu quotidien de football, incluant les équipes universitaires, les équipes professionnelles et les principaux comptes médias sportifs partageant une couverture majeure du football.",
          "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, spécifié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

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
curated_category_id required	Une référence à la Curated Category que vous utilisez 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": "Soccer",
        "description": "Run next to the best of everyday soccer content including college teams, professional teams, and the top sports media handles sharing major soccer coverage.",
        "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 et accessibles par ce compte publicitaire. Les fonctionnalités sont indiquées par une clé de fonctionnalité descriptive et ne sont exposées sur ce point de terminaison que si elles sont introduites en version bêta ou dans le cadre d’une diffusion limitée et qu’elles sont disponibles dans l’Ads API. Les fonctionnalités qui ne répondent pas à ces critères ne seront pas exposées sur ce point de terminaison.

Remarque : ce point de terminaison sert à faciliter le développement de l’écosystème de l’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 faites que par l’annonceur auprès de son responsable de compte X.

URL de la ressource

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

Paramètres

Nom	Description
account_id required	Identifiant du compte concerné. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’Advertiser API à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
feature_keys optional	Paramètre optionnel qui permet 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 Valeurs possibles : REACH_AND_FREQUENCY_ANALYTICS, REACH_FREQUENCY_CAP, WEBSITE_CLICKS_CPM_BILLING

Exemple de requête

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

Exemple de réponse

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t"
        }
      },
      "data": [
        "CITY_TARGETING",
        "CONVERSATION_CARD",
        "PROMOTED_MEDIA_POLLS",
        "REACH_AND_FREQUENCY_ANALYTICS",
        "REACH_FREQUENCY_CAP",
        "UNIVERSAL_LOOKALIKE"
      ]
    }

​

POST accounts/:account_id/features

SANDBOX UNIQUEMENT

Ajoute une fonctionnalité à un compte sandbox.

La liste à jour des fonctionnalités de compte peut être récupérée via le endpoint GET accounts/:account_id/features.

URL de la ressource

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

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 : gq180y
feature_keys requis	Liste, séparée par des virgules, des 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

Supprimer une fonctionnalité d’un compte sandbox.

La liste actualisée des fonctionnalités de compte peut être récupérée via le point de terminaison GET accounts/:account_id/features.

URL de la ressource

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

Paramètres

Nom	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : gq180y
feature_keys required	Liste de fonctionnalités de compte, séparées par des virgules, à supprimer du 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

Requête d’exemple

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

Réponse d’exemple

    {
      "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 l’ensemble des 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

Nom	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. 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 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
funding_instrument_ids optional	Limite la réponse aux seuls 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 Exemple : 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 Exemple : created_at-asc
with_deleted optional	Inclut les résultats supprimés dans votre requête. Type : boolean Valeur par défaut : false Valeurs possibles : true, false
with_total_count optional	Inclut l’attribut de réponse total_count. Remarque : ce paramètre et cursor sont exclusifs. Remarque : les requêtes qui incluent total_count auront des limites de taux plus faibles, actuellement fixées à 200 par tranche de 15 minutes. Type : boolean Valeur par défaut : false Valeurs possibles : true, false

Exemple de requête

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 ending in 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.

Resource URL

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

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 Exemple : 18ce54d4x5t
funding_instrument_id required	Référence à l’instrument de financement que vous utilisez dans la requête. Type : string Exemple : lygyi
with_deleted optional	Inclure les résultats supprimés dans votre requête. Type : boolean Valeur par défaut : false Valeurs possibles : true, false

Example Request

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

Example Response

    {
      "request": {
        "params": {
          "funding_instrument_id": "lygyi",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "start_time": "2016-07-22T04:24:04Z",
        "description": "Visa ending in 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ée 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 dans le sandbox.

URL de ressource

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

Paramètres

Nom	Description
account_id required	L’identifiant du compte concerné. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Exemple : gq1844
currency required	La devise, exprimée au format ISO-4217. Type: string Exemple : USD
start_time required	La date à laquelle l’instrument de financement devient actif et peut être utilisé, exprimée au format ISO 8601. Type: string Exemple : 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 Exemple : 2017-05-26T07:00:00Z
credit_limit_local_micro optional	Le crédit total disponible pour cet instrument de financement. Note : Applicable uniquement à certains types d’instruments de financement. Type: long Exemple : 37500000
funded_amount_local_micro optional	Le montant total du budget alloué à cet instrument de financement. Note : Applicable uniquement à certains types d’instruments de financement. Type: long Exemple : 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": "(aucun moyen de paiement n'a encore été configuré)",
        "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	Identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’Advertiser API à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : gq1844
funding_instrument_id required	Référence à l’instrument de financement que vous utilisez dans 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": "(no payment method has been set up yet)",
        "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

Lancer dans Postman

​

GET iab_categories

Récupérez les categories d’applications valides pour les groupes d’annonces (line_items).

URL de la ressource

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

Paramètres

Name	Description
count optional	Indique le nombre d’enregistrements à tenter de récupérer par requête. Type : int Valeur par défaut : 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 Exemple : gc-ddf4a
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 qui incluent total_count auront des limites de taux plus faibles, actuellement définies à 200 toutes les 15 minutes. Type : boolean Valeur par défaut : false Valeurs possibles : true, false

Exemple de requête

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

Exemple de réponse

    {
      "data": [
        {
          "id": "IAB1",
          "parent_id": null,
          "name": "Arts & Entertainment"
        },
        {
          "id": "IAB1-1",
          "parent_id": "IAB1",
          "name": "Books & Literature"
        }
      ],
      "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.

URL de la ressource

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

Paramètres

Nom	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
campaign_ids optional	Restreint la réponse aux seuls line items associés à des campagnes spécifiques en indiquant une liste d’identifiants séparés par des virgules. Jusqu’à 200 ID 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. Consultez la section Pagination pour plus d’informations. Type: string Example: 8x7v00oow
funding_instrument_ids optional	Restreint la réponse aux seuls line items associés à des instruments de financement spécifiques en indiquant une liste d’identifiants séparés par des virgules. Jusqu’à 200 ID peuvent être fournis. Type: string Example: lygyi
line_item_ids optional	Restreint la réponse aux seuls line items souhaités en indiquant une liste d’identifiants séparés par des virgules. Jusqu’à 200 ID peuvent être fournis. Type: string Example: 8v7jo
q optional	Requête 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. Consultez la section 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_draft optional	Inclut 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	Inclut l’attribut de réponse total_count. Note : ce paramètre et cursor sont exclusifs. Note : les requêtes qui incluent total_count auront des limites de taux plus faibles, actuellement définies à 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/line_items?line_item_ids=itttx

Exemple de réponse

    {
      "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 line item spécifique associé au compte actuel.

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 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_id requis	Une référence au line item que vous utilisez dans la requête. Type : string Exemple : 8v7jo
with_deleted optionnel	Inclure les résultats supprimés dans votre requête. Type : boolean Valeur par défaut : false Valeurs possibles : true, false

Exemple de requête

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éez un élément de campagne associé à la campagne spécifiée appartenant au compte actuel.

Tous les éléments de campagne au sein d’une campagne doivent avoir 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 mobile en plus de l’emplacement PROMOTED_ACCOUNT standard.

Le fait de définir android_app_store_identifier ou ios_app_store_identifier ajoutera automatiquement les critères de ciblage pour l’élément de campagne correspondant à l’application mobile promue ; par exemple, fournir ios_app_store_identifier ajouterait le critère de ciblage PLATFORM (critères de ciblage) pour iOS.

Remarque : la limite est de 100 éléments de campagne par campagne et de 256 éléments de campagne actifs pour l’ensemble des campagnes.

URL de la ressource

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

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 : 18ce54d4x5t
campaign_id obligatoire	L’identifiant de la campagne dans laquelle créer l’élément de campagne. Type: string Exemple : 8slvg
end_time obligatoire	L’heure à laquelle l’élément de campagne cessera d’être diffusé, exprimée au format ISO 8601. Type : string Exemple : 2017-10-05T00:00:00Z
objectif obligatoire	L’objectif de campagne pour cet élément de campagne. Type : enum Valeurs possibles : APP_ENGAGEMENTS, APP_INSTALLS, REACH, FOLLOWERS, ENGAGEMENTS, VIDEO_VIEWS, PREROLL_VIEWS, WEBSITE_CLICKS
placements obligatoire	L’emplacement ou les emplacements où cet élément de campagne sera diffusé. Indiquez une liste, séparée par des virgules, de valeurs d’emplacement. 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 obligatoire	Le type de produit promu que contiendra cet élément de campagne. Type : enum Valeurs possibles : MEDIA, PROMOTED_ACCOUNT, PROMOTED_TWEETS
start_time obligatoire	L’horodatage, exprimé au format ISO 8601, à partir duquel l’élément de campagne commencera à être diffusé. Type : string Exemple : 2017-07-05T00:00:00Z
advertiser_domain parfois obligatoire	Le nom de domaine du site web de cet annonceur, sans le protocole. Remarque : Obligatoire lorsque le placement de la line item est défini sur PUBLISHER_NETWORK. Type: string Exemple : x.com
android_app_store_identifier parfois requis	Identifiant Google Play pour les applications promues. Remarque : les objectifs APP_INSTALLS et APP_ENGAGEMENTS exigent de définir au moins un identifiant d’app store — soit android_app_store_identifier, soit ios_app_store_identifier. Type : chaîne de caractères Exemple : com.twitter.android
bid_amount_local_micro parfois obligatoire	Le montant de l’enchère à associer à cet élément de campagne. La devise associée à l’instrument de financement spécifié sera utilisée. Pour un montant en USD, 5,50 $ est représenté sous la forme 5500000. Remarque : obligatoire si bid_strategy est défini sur MAX ou TARGET. Remarque : seules les valeurs strictement supérieures à zéro sont acceptées. Type : long Exemple : 5500000
catégories parfois obligatoire	Les catégories IAB pertinentes pour cet annonceur. Voir GET iab_categories. Remarque : Obligatoire lorsque le placement de l’élément de campagne est défini sur PUBLISHER_NETWORK. Type : string Exemple : IAB3-1
ios_app_store_identifier parfois obligatoire	La partie numérique de l’identifiant Apple App Store pour les applications promues. Remarque : les objectifs APP_INSTALLS et APP_ENGAGEMENTS imposent la définition d’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 associée à cet élément d’insertion. Remarque : obligatoire lorsque l’objectif de l’élément d’insertion est défini sur WEBSITE_CONVERSIONS. Type : string Exemple : nvo4z
advertiser_user_id facultatif	L’identifiant d’utilisateur X du compte qui fait la promotion d’une annonce PREROLL_VIEWS. Seules certaines applications clientes peuvent utiliser ce paramètre. Type: string Exemple : 312226591
audience_expansion facultatif	Utilisé pour étendre la portée de la campagne en ciblant des utilisateurs similaires à ceux déjà ciblés. Remarque : par défaut, aucune extension ne sera appliquée. Type: enum Valeurs possibles : BROAD, DEFINED, EXPANDED
bid_strategy facultatif	Le mécanisme d’enchères. AUTO optimise automatiquement les enchères en fonction du budget quotidien et des dates de diffusion de la 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 à moins de 20 % de la valeur bid_amount_local_micro spécifiée et est disponible lorsque l’objectif est défini sur REACH, FOLLOWERS ou WEBSITE_CLICKS. Remarque : si la valeur est définie sur AUTO, bid_amount_local_micro sera ignoré. Remarque : valeur par défaut en fonction de l’objectif. Type : enum Valeurs possibles : AUTO, MAX, TARGET
duration_in_days facultatif	La période pendant laquelle le frequency_cap est atteint. Type: int Valeurs possibles : 1, 7, 30
entity_status facultatif	Le statut de l’élément de campagne. Type: enum Valeur par défaut : ACTIVE Valeurs possibles : ACTIVE, DRAFT, PAUSED
frequency_cap facultatif	Le nombre maximal 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 campagne. 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 le recours à un partenaire MACT pris en charge. L’option SITE_VISITS est uniquement disponible avec l’objectif WEBSITE_CLICKS. Remarque : valeur par défaut en fonction de 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
nom facultatif	Le nom de l’élément de campagne. Type : string Exemple : demo Longueur minimale et maximale : 1, 255
pay_by facultatif	L’unité utilisée pour facturer 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 la 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 la valeur IMPRESSION. Type : enum Valeurs possibles : APP_CLICK, IMPRESSION, LINK_CLICK
standard_delivery facultatif	Activer la diffusion standard ou accélérée. Voir Budget Pacing pour plus d’informations sur la diffusion standard et la diffusion accélérée. Disponible uniquement si budget_optimization a la valeur LINE_ITEM pour la campagne parente Type: boolean Par défaut : true Valeurs possibles : true, false
total_budget_amount_local_micro facultatif	Le montant total du budget à allouer à l’élément de campagne. La devise associée à l’instrument de financement spécifié sera utilisée. Pour les montants en USD, 37,50 $ est représenté par 37500000. Type : long Exemple : 37500000
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 un montant en USD, 5,50 $ est représenté par 5500000. Lorsque ce paramètre n’est pas fourni, la campagne répartira les dépenses de manière uniforme en fonction du budget total et sur toute la durée de diffusion de la campagne. Uniquement disponible lorsque budget_optimization est défini sur LINE_ITEM pour la campagne parente Remarque : ce montant doit être inférieur ou égal à 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 la création par lot de nouvelles line items avec 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, qu’il s’agisse d’erreurs ou de succès, préservent l’ordre des éléments de la requête initiale.

Réponses par lot

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

Erreurs de lot

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

Resource URL

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

Parameters

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 pour les objets line item. Pour une liste des paramètres requis et facultatifs des line items, voir ici.

Example Request

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 la ligne publicitaire spécifiée pour le compte actuel.

URL de la ressource

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

Paramètres

Nom	Description
account_id obligatoire	L’identifiant du compte concerné. Apparaît dans le chemin de la ressource et est 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 Exemple : 18ce54d4x5t
line_item_id obligatoire	Une référence à l’élément de ligne que vous manipulez dans la requête. Type : string Exemple : 8v7jo
advertiser_domain facultatif	Le domaine du site web de cet annonceur, sans la spécification du protocole. Remarque : requis lorsque l’emplacement de l’élément de campagne est défini sur PUBLISHER_NETWORK. Type : string Exemple : x.com
advertiser_user_id facultatif	L’identifiant utilisateur Twitter du compte qui fait la promotion d’une publicité de type PREROLL_VIEWS. Seules certaines applications clientes peuvent utiliser ce paramètre. Type : string Exemple : 312226591
android_app_store_identifier facultatif	L’identifiant Google Play Store de l’application promue. Remarque : les objectifs APP_INSTALLS et APP_ENGAGEMENTS exigent la définition d’au moins un identifiant de boutique d’applications : soit android_app_store_identifier, soit ios_app_store_identifier. Type : string Exemple : com.twitter.android
audience_expansion facultatif	Utilisé pour élargir la portée des campagnes en ciblant des utilisateurs similaires à ceux déjà visés. Type : enum Valeurs possibles : BROAD, DEFINED, EXPANDED
bid_amount_local_micro facultatif	Le montant de l’enchère à associer à cet élément de campagne. La devise associée à l’instrument de financement spécifié sera utilisée. Pour les dollars américains, 5,50 $ est représenté par 5500000. Remarque : obligatoire 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 facultatif	Le mécanisme d’enchères. AUTO optimise automatiquement les enchères en fonction du budget quotidien et des dates de diffusion de la campagne. MAX fixe 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 une fourchette de 20 % du bid_amount_local_micro spécifié et est disponible lorsque l’objectif est défini sur REACH ou WEBSITE_CLICKS. Remarque : si la valeur est définie sur AUTO, bid_amount_local_micro sera ignoré. Remarque : valeur par défaut selon l’objectif. Type : enum Valeurs possibles : AUTO, MAX, TARGET
categories facultatif	Les catégories IAB pertinentes pour cet annonceur. Consultez GET iab_categories. Remarque : Obligatoire lorsque le placement de la line item est défini sur PUBLISHER_NETWORK. Type : string Exemple : IAB3-1
duration_in_days facultatif	La période (en jours) sur laquelle s’applique le frequency_cap. Type: int Valeurs possibles : 1, 7, 30
entity_status facultatif	Statut de l’élément de campagne. Type : enum Valeurs possibles : ACTIVE, PAUSED
end_time facultatif	L’heure, exprimée au format ISO 8601, à laquelle la diffusion de l’élément de campagne s’arrêtera. Type: string Exemple: 2017-10-05T00:00:00Z
frequency_cap optionnel	Le nombre maximal de fois qu’une annonce peut être diffusée à un même utilisateur. Remarque : Uniquement pris en charge pour les objectifs REACH, ENGAGEMENTS, VIDEO_VIEWS et PREROLL_VIEWS. Type : int Exemple : 5
goal facultatif	Le paramètre d’optimisation à utiliser pour cet élément de campagne. 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 déterminée par 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 facultatif	La partie numérique de l’identifiant Apple App Store pour les applications promues. Remarque : les objectifs APP_INSTALLS et APP_ENGAGEMENTS exigent la définition d’au moins un identifiant d’App Store — soit android_app_store_identifier, soit ios_app_store_identifier. Type : chaîne de caractères Exemple : 333903271
nom facultatif	Nom de l’élément de campagne. Type : string Exemple : demo
pay_by facultatif	L’unité de facturation pour cet élément de campagne. Ce paramètre ne peut être modifié que pour les éléments de campagne utilisant l’objectif APP_INSTALLS. Remarque : la valeur par défaut de pay_by est automatiquement définie en fonction de l’objectif de la campagne et de l’unité d’enchère de l’élément de campagne. 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 lorsque TARGET est défini pour bid_strategy. L’objectif SITE_VISITS prend en charge la valeur IMPRESSION. Type : enum Valeurs possibles : APP_CLICK, IMPRESSION, LINK_CLICK
start_time facultatif	L’heure, exprimée au format ISO 8601, à laquelle l’élément de campagne commencera à être diffusé. Type : string Exemple : 2017-07-05T00:00:00Z
total_budget_amount_local_micro facultatif	Le montant total du budget à allouer à l’élément de campagne (line item). 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 facultatif	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. Lorsque ce paramètre n’est pas renseigné, la campagne dépensera de manière uniforme en fonction du budget total et de la durée de la période de diffusion de la campagne. Uniquement disponible lorsque budget_optimization est défini sur LINE_ITEM pour la campagne parente Remarque : ce montant doit être inférieur ou égal à 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 campagne spécifié appartenant au compte en cours.

Remarque : la suppression d’un élément de campagne est irréversible et toute tentative ultérieure de suppression de la ressource renverra une réponse HTTP 404.

Remarque : lorsqu’un élément de campagne est supprimé, ses promoted_tweets enfants 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 spécifié dans la requête. Ces promoted_tweets ne sont toutefois pas réellement supprimés ("deleted": false dans la réponse). Nous n’effectuons pas de suppressions en cascade.

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 est généralement un paramètre requis pour toutes les requêtes Advertiser API, à 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 campagne sur lequel porte la requête. Type : string Exemple : 9f2ix

Exemple de requête

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

Exemple de réponse

    {
      "data": {
        "bid_strategy": "MAX",
        "advertiser_user_id": "756201191646691328",
        "name": "Untitled",
        "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 pour les éléments de campagne

Lancer dans Postman

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

​

GET accounts/:account_id/line_item_curated_categories

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

URL de la ressource

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

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 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
count optionnel	Spécifie le nombre d’enregistrements à tenter de récupérer par requête. Type : int Valeur par défaut : 200 Min, Max : 1, 1000
cursor optionnel	Spécifie un curseur pour obtenir la page de résultats suivante. Voir Pagination pour plus d’informations. Type : string Exemple : 8x7v00oow
sort_by optionnel	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 optionnel	Inclure les résultats supprimés dans votre requête. Type : booléen Valeur par défaut : false Valeurs possibles : true, false
with_total_count optionnel	Inclure l’attribut de réponse total_count. Remarque : Ce paramètre et cursor sont mutuellement exclusifs. Remarque : Les requêtes qui incluent total_count auront des limites de taux plus basses, actuellement fixées à 200 par tranche de 15 minutes. Type : booléen 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

Exemple de réponse

    {
      "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 organisée d’élément de campagne spécifique associée au compte actuel.

URL de la ressource

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

Paramètres

Name	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
line_item_curated_category_id required	Référence à la catégorie organisée d’élément de campagne avec laquelle vous opérez dans la requête. Type : string Exemple : 43853bhii885
with_deleted optional	Inclut les résultats supprimés dans votre 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

Associer un objet curated category à l’élément de campagne (line item) spécifié.

URL de ressource

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

Paramètres

Nom	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’Advertiser API, à 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 que vous utilisez dans la requête. Type: string Exemple: 10miy
line_item_id required	Référence à l’élément de campagne (line item) que vous utilisez 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 campagne spécifié.

Resource URL

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

Parameters

Name	Description
account_id required	L’identifiant du compte utilisé. Il apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte indiqué doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
line_item_curated_category_id required	Référence à la catégorie sélectionnée d’élément de campagne 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 campagne utilisé dans la requête. Type : string Exemple : 8v7jo

Example Request

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

Example Response

    {
      "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 de line item organisée spécifiée.

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 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
line_item_curated_category_id required	Référence à la catégorie de line item organisée sur laquelle vous opérez 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 des éléments de campagne

Exécuter dans Postman

​

GET line_items/placements

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

Resource URL

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

Parameters

Name	Description
product_type optional	Limite la réponse aux seuls placements valides pour le type de produit spécifié. Type : enum Valeurs possibles : MEDIA, PROMOTED_ACCOUNT, PROMOTED_TWEETS

Example Request

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

Example Response

    {
      "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érer les détails de certaines 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	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
campaign_id optional	Limite la réponse aux créations média associées à la campagne spécifiée. Type: string Exemple: 8gdx6
count optional	Spécifie le nombre d’enregistrements à tenter de récupérer par requête distincte. Type: int Valeur par défaut: 200 Min, Max: 1, 1000
cursor optional	Spécifie un curseur pour obtenir la page suivante de résultats. Voir Pagination pour plus d’informations. Type: string Exemple: 8x7v00oow
line_item_ids optional	Limite la réponse aux créations média associées aux postes budgétaires spécifiés en fournissant une liste d’identifiants séparés par des virgules. Jusqu’à 200 ID peuvent être fournis. Type: string Exemple: 8v7jo
media_creative_ids optional	Limite 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 Exemple: 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 Exemple: created_at-asc
with_deleted optional	Inclut les résultats supprimés dans votre requête. Type: boolean Valeur par défaut: false Valeurs possibles: true, false
with_total_count optional	Inclut l’attribut de réponse total_count. Remarque : ce paramètre et cursor sont exclusifs. Remarque : les requêtes qui incluent total_count auront des limites de taux plus faibles, actuellement définies à 200 par tranches de 15 minutes. Type: boolean Valeur par défaut: false Valeurs possibles: 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

Renvoie les détails d’un media creative spécifique associé au compte actuel.

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 Example: 18ce54d4x5t
media_creative_id required	Une référence au media creative que vous manipulez dans la requête. Type: string Example: 43853bhii885
with_deleted optional	Inclure les résultats supprimés dans votre requête. 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

Associez un objet account media à l’élément de campagne (line item) spécifié.

Utilisez cet endpoint pour promouvoir des publicités in-stream (quand 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.

URL de la ressource

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

Paramètres

Nom	Description
account_id required	L’identifiant du compte utilisé. Il apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes Advertiser API, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
account_media_id required	Une référence à l’entité account media avec laquelle vous travaillez dans la requête. Type : string Exemple : 10miy
line_item_id required	Une référence à l’élément de campagne (line item) avec lequel vous travaillez dans la requête. Type : string Exemple : 8v7jo
landing_url sometimes required	L’URL du site web vers lequel diriger un utilisateur. Elle doit uniquement être utilisée avec des images TAP (ou « display creatives »). Cette valeur sera ignorée si elle est utilisée avec des ressources preroll. Pour associer une URL à une ressource preroll, utilisez l’endpoint POST accounts/:account_id/preroll_call_to_actions. Remarque : obligatoire lorsque l’objectif de l’élément de campagne est défini sur WEBSITE_CLICKS. Type : string Exemple : https://blog.x.com/

Exemple de requête

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

Exemple de réponse

    {
      "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 associée au compte actuel.

URL de la ressource

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

Paramètres

Name	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’Advertiser API, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
media_creative_id required	Une 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

Lancer dans Postman

​

GET accounts/:account_id/promoted_accounts

Récupérer les détails de certains ou de tous les comptes sponsorisés associés à un ou plusieurs éléments de campagne (line items) du compte actuel.

Utilisez GET users/lookup pour obtenir les données des comptes utilisateur 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 sponsorisés.

Resource URL

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

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 Exemple: 18ce54d4x5t
count optional	Spécifie le nombre d’enregistrements à récupérer par requête distincte. Type: int Valeur par défaut: 200 Min, max: 1, 1000
cursor optional	Spécifie un curseur pour obtenir la page de résultats suivante. Voir Pagination pour plus d’informations. Type: string Exemple: 8x7v00oow
line_item_ids optional	Restreint la réponse aux seuls comptes sponsorisés associés aux éléments de campagne spécifiés, en fournissant une liste d’identifiants séparés par des virgules. Jusqu’à 200 ID peuvent être fournis. Type: string Exemple: 9bpb2
promoted_account_ids optional	Restreint la réponse aux seuls comptes sponsorisés souhaités, en fournissant une liste d’identifiants séparés par des virgules. Jusqu’à 200 ID peuvent être fournis. Type: string Exemple: 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 Exemple: created_at-asc
with_deleted optional	Inclut les résultats supprimés dans votre requête. Type: boolean Valeur par défaut: false Valeurs possibles: true, false
with_total_count optional	Inclut l’attribut de réponse total_count. Remarque : ce paramètre et cursor sont mutuellement exclusifs. Remarque : les requêtes qui incluent total_count auront des limites de taux plus basses, actuellement fixées à 200 par 15 minutes. Type: boolean Valeur par défaut: false Valeurs possibles: 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 line item du compte actuel.

Resource URL

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

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 Exemple : 18ce54d4x5t
promoted_account_id required	Référence au compte promu utilisé dans la requête. Type : string Exemple : 19pl2
with_deleted optional	Inclure les résultats supprimés dans votre requête. Type : boolean Valeur par défaut : false Valeurs possibles : 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

Associe 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é à des comptes sponsorisés (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 de gestion de campagnes.

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

URL de la ressource

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

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’Advertiser API, à 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 campagne (line item) utilisé dans la requête. Type : string Exemple : 9bpb2
user_id required	Une référence à l’utilisateur utilisé dans la requête. Utilisez GET users/lookup pour récupérer un user ID à partir d’un nom d’écran (screen name). Type : long Exemple : 756201191646691328

Exemple de requête

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

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-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 (line item) spécifié.

Resource URL

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

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’Advertiser API, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
promoted_account_id required	Identifiant de l’instance de Promoted Account associée à un élément de campagne (line item). Type : string Exemple : 19pl2

Example Request

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

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-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érer les références aux Tweets associés aux éléments de ligne (line items) du compte actuel.

Utilisez le point de terminaison 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 (line items) 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).

URL de la ressource

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

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
count optionnel	Spécifie le nombre d’enregistrements à tenter de récupérer par requête distincte. Type : int Valeur par défaut : 200 Min, Max : 1, 1000
cursor optionnel	Spécifie un curseur pour obtenir la page de résultats suivante. Voir Pagination pour plus d’informations. Type : string Exemple : 8x7v00oow
line_item_ids optionnel	Limite la réponse aux seuls Tweets associés à des éléments de ligne (line items) spécifiques en indiquant une liste d’identifiants séparés par des virgules. Jusqu’à 200 identifiants peuvent être fournis. Type : string Exemple : 96uzp
promoted_tweet_ids optionnel	Limite la réponse aux seuls Tweets promus souhaités en indiquant une liste d’identifiants séparés par des virgules. Jusqu’à 200 identifiants peuvent être fournis. Type : string Exemple : 1efwlo
sort_by optionnel	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 optionnel	Inclut les résultats supprimés dans votre requête. Type : boolean Valeur par défaut : false Valeurs possibles : true, false
with_total_count optionnel	Inclut l’attribut de réponse total_count. Remarque : ce paramètre et cursor sont mutuellement exclusifs. Remarque : les requêtes qui incluent total_count auront des limites de taux plus faibles, actuellement fixées à 200 par tranche de 15 minutes. Type : boolean Valeur par défaut : false Valeurs possibles : true, false

Exemple de requête

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

Exemple de réponse

    {
      "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érer une référence spécifique à un Tweet associé à un élément de campagne pour le compte actuel.

Remarque : lorsque les éléments de campagne 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).

URL de la ressource

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

Paramètres

Nom	Description
account_id obligatoire	Identifiant du compte utilisé. Il 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 spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
promoted_tweet_id obligatoire	Référence au Tweet promu sur lequel porte votre requête. Type : string Exemple : 1efwlo
with_deleted optionnel	Inclure les résultats supprimés dans votre requête. Type : boolean Valeur par défaut : false Valeurs possibles : true, false

Exemple de requête

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

Exemple de réponse

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

Associer un ou plusieurs Tweets à l’élément de campagne (line item) spécifié. Tous les Tweets ne sont pas adaptés à la promotion, selon l’objectif de la campagne. Veuillez consulter la page Objective-based Campaigns pour plus d’informations.

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

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

URL de la ressource

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

Paramètres

Nom	Description
account_id requis	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’Ads API, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
line_item_id requis	Référence à l’élément de campagne (line item) utilisé dans la requête. Type : string Exemple : 8v7jo
tweet_ids requis	Liste, séparée par des virgules, d’identifiants correspondant à des Tweets spécifiques. Jusqu’à 50 identifiants peuvent être fournis. Type : long Exemple : 822333526255120384

Exemple de requête

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

Exemple de réponse

    {
      "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 (line item) spécifié.

Remarque : une entité promoted_tweets supprimée sera indiquée comme « Paused » dans l’interface ads.x.com. De même, le fait de la mettre en « pause » depuis l’interface dissociera le Tweet de son élément de campagne.

URL de ressource

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

Paramètres

Nom	Description
account_id obligatoire	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
promoted_tweet_id obligatoire	L’identifiant fait référence à l’instance d’un Tweet sponsorisé (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 Exemple : 1gp8a5

Exemple de requête

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

Exemple de réponse

    {
      "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 pouvant être promus

Exécuter dans Postman

​

GET accounts/:account_id/promotable_users

Récupérer les détails pour certains ou tous les utilisateurs promouvables associés 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 et contacter X pour que cet utilisateur soit ajouté à votre compte en tant qu’utilisateur promouvable RETWEETS_ONLY.

À condition que les autorisations soient correctement définies, vous pouvez effectuer des requêtes vers les endpoints de produits promus qui font directement référence à 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 Twitter Ads.

Vous n’êtes pas obligé de retweeter le Tweet cible. Lorsque vous faites la promotion d’un Tweet avec cette approche, le tweet_id renvoyé sera différent de l’ID du Tweet fourni. En coulisses, le Tweet est retweeté comme un Tweet « nullcasted », 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

Paramètres

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
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 de résultats suivante. Voir Pagination pour plus d’informations. Type: string Example: 8x7v00oow
promotable_user_ids optional	Permet de limiter la réponse aux seuls utilisateurs promouvables souhaités en spécifiant une liste d’identifiants séparés par des virgules. Jusqu’à 200 identifiants peuvent être fournis. Type: string Example: l310s
sort_by optional	Trie selon un attribut pris en charge, dans l’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. 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 toutes les 15 minutes. Type: boolean Default: false Possible values: true, false

Exemple de requête

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

Exemple de réponse

    {
      "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érer 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. À condition que les autorisations soient correctement définies, 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’êtes pas obligé de retweeter le Tweet cible. Lorsque vous faites la promotion d’un Tweet avec cette approche, le tweet_id renvoyé sera différent de l’ID du Tweet fourni. En coulisses, le Tweet est retweeté en tant que Tweet 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

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
promotable_user_id optional	Une référence à l’utilisateur promouvable sur lequel porte la requête Type : string Exemple : l310s
with_deleted optional	Inclure les résultats supprimés dans votre requête. Type : boolean Valeur par défaut : false Valeurs possibles : true, false

Exemple de requête

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érer une liste d’informations sur les éditeurs de catégories de contenu

Des informations supplémentaires sont disponibles dans le guide sur l’objectif Vues de vidéos en pré‑roll

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, une seule recommandation est disponible par instrument de financement.

URL de la ressource

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

Paramètres

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

Exemple de requête

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

Exemple de réponse

    "request": {
      "params": {
        "account_id": "18ce54d4x5t"
      }
    },
    "total_count": 1,
    "data": [
      {
        "funding_instrument_id": "gpvzb",
        "id": "62ce8zza1q0w",
        "account_id": "18ce54d4x5t",
        "status": "PENDING",
        "message": "Recommendation for testing",
        "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ère une recommandation de campagne spécifique associée à ce compte publicitaire.

La recommandation de campagne contient un ensemble complet de modifications suggéré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 la Batch API, mais elle peut également être associée à des endpoints de mise à jour individuels selon le cas (Create pour POST, Update pour PUT, Delete pour DELETE).

URL de ressource

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

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 Advertiser API, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
recommendation_id requis	Une référence à l’ID de recommandation faisant l’objet de la requête. Type : string Exemple : 62ce8zza1q0w

Exemple de requête

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

Exemple de réponse

{
    "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": "Update",
          "dependent_entities": [
            {
              "entity_type": "line_items",
              "params": {
                "name": "Campagne de recommandations",
                "placements": [
                  "TWITTER_TIMELINE"
                ],
                "bid_amount_local_micro": 1430000,
                "id": "6f5kq",
                "include_sentiment": "ALL"
              },
              "operation_type": "Update",
              "dependent_entities": [
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "id": "a8po6p"
                  },
                  "operation_type": null,
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "résultats des élections",
                    "targeting_value": "résultats des élections",
                    "targeting_type": "PHRASE_KEYWORD"
                  },
                  "operation_type": "Create",
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "id": "101ftp"
                  },
                  "operation_type": "Delete",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "Homme",
                    "targeting_value": 1,
                    "targeting_type": "GENDER"
                  },
                  "operation_type": "Create",
                  "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": "Create",
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "id": "101fto"
                  },
                  "operation_type": "Delete",
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "line_item_id": "6f5kq",
                    "display_properties": [],
                    "paused": false,
                    "approval_status": "ACCEPTED",
                    "tweet_id": "91125952589766656"
                  },
                  "operation_type": "Create",
                  "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": "Create",
                  "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": "Create",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "id": "a8po6o"
                  },
                  "operation_type": "Delete",
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "line_item_id": "6f5kq",
                    "display_properties": [],
                    "paused": false,
                    "approval_status": "ACCEPTED",
                    "tweet_id": "991101965843460096"
                  },
                  "operation_type": "Create",
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "line_item_id": "6f5kq",
                    "display_properties": [],
                    "paused": false,
                    "approval_status": "ACCEPTED",
                    "tweet_id": "991127212156096516"
                  },
                  "operation_type": "Create",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "débat",
                    "targeting_value": "débat",
                    "targeting_type": "NEGATIVE_PHRASE_KEYWORD"
                  },
                  "operation_type": "Create",
                  "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": "PENDING",
      "message": "Recommandation de test",
      "created_at": "2016-11-14T23:07:54Z",
      "updated_at": "2016-11-14T23:07:54Z"
      }
    }

​

Promoted Tweets programmés

Exécuter dans Postman

​

GET accounts/:account_id/scheduled_promoted_tweets

Récupérer les détails de certains ou de l’ensemble des Tweets sponsorisés programmé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	Identifiant du compte concerné. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
count optional	Spécifie le nombre d’enregistrements à tenter de récupérer par requête distincte. Type : int Valeur par défaut : 200 Min., max. : 1, 1000
cursor optional	Spécifie un curseur pour obtenir la page suivante de résultats. Voir Pagination pour plus d’informations. Type : string Exemple : 8x7v00oow
line_item_ids optional	Restreint la réponse uniquement aux Tweets programmés associés à des line items spécifiques en indiquant une liste d’identifiants séparés par des virgules. Jusqu’à 200 IDs peuvent être fournis. Type : string Exemple : 8xdpe
scheduled_promoted_tweet_ids optional	Restreint la réponse uniquement aux Tweets sponsorisés programmés souhaités en indiquant une liste d’identifiants séparés par des virgules. Jusqu’à 200 IDs peuvent être fournis. Type : string Exemple : 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 Exemple : created_at-asc
with_deleted optional	Inclut les résultats supprimés dans votre requête. Type : boolean Valeur par défaut : false Valeurs possibles : true, false
with_total_count optional	Inclut l’attribut de réponse total_count. Remarque : ce paramètre et cursor sont exclusifs. Remarque : les requêtes qui incluent total_count auront des limites de taux plus faibles, actuellement fixées à 200 par tranche de 15 minutes. Type : boolean Valeur par défaut : false Valeurs possibles : true, false

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 programmé spécifique associé au compte actuel.

URL de la ressource

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

Paramètres

Nom	Description
account_id required	L’identifiant du compte utilisé. Il apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’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 required	Référence au Tweet promu programmé concerné par la requête. Type: string Exemple : 1xboq
with_deleted optional	Inclure les résultats supprimés dans votre requête. Type: boolean Valeur par défaut : false Valeurs possibles : true, false

Exemple de requête

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

Associe un Tweet programmé à l’élément de campagne (line item) spécifié.

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

URL de la ressource

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

Paramètres

Name	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes Advertiser API, à 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 campagne (line item) concerné par la requête. Type: string Exemple: 8xdpe
scheduled_tweet_id required	Une référence au Tweet programmé concerné par la requête. Type: long Exemple: 870358555227860992

Exemple de requête

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

Exemple de réponse

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

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

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

URL de la ressource

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

Paramètres

Nom	Description
account_id requis	Identifiant du compte utilisé. Il apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’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 requis	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 Exemple : 1xtfl

Exemple de requête

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

Exemple de réponse

    {
      "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érer les détails de certains ou de l’ensemble des critères de ciblage associés aux éléments de campagne du compte actuel.

URL de la ressource

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

Paramètres

Name	Description
account_id required	L’identifiant du compte utilisé. Il apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
line_item_ids required	Limite la réponse aux seuls critères de ciblage des é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 Exemple : 8u94t
count optional	Spécifie le nombre d’enregistrements à récupérer par requête distincte. Type : int Valeur par défaut : 200 Min, Max : 1, 1000
cursor optional	Spécifie un curseur pour obtenir la page de résultats suivante. Voir Pagination pour plus d’informations. Type : string Exemple : 8x7v00oow
lang optional	Un code de langue ISO-639-1. Lorsqu’il est renseigné, un attribut supplémentaire localized_name est renvoyé dans la réponse pour les objets pour lesquels un nom localisé est disponible. Type : string Exemple : 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 Exemple : created_at-asc
targeting_criterion_ids optional	Limite la réponse aux seuls critères de ciblage souhaités en indiquant une liste d’identifiants séparés par des virgules. Jusqu’à 200 ID peuvent être fournis. Type : string Exemple : dpl3a6
with_deleted optional	Inclut les résultats supprimés dans votre requête. Type : boolean Valeur par défaut : false Valeurs possibles : true, false
with_total_count optional	Inclut l’attribut de réponse total_count. Remarque : ce paramètre et cursor sont exclusifs. Remarque : les requêtes qui incluent total_count auront des limites de taux plus faibles, actuellement fixées à 200 par tranche de 15 minutes. Type : boolean Valeur par défaut : false Valeurs possibles : true, false

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": "Custom audience targeting",
          "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 actuel.

Resource URL

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

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 Exemple : 18ce54d4x5t
targeting_criterion_id required	Référence au critère de ciblage que vous utilisez dans la requête. Type: string Exemple : eijd4y
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 pour lesquels un nom localisé est disponible. Type: string Exemple : fr
with_deleted optional	Inclure les résultats supprimés dans la requête. Type: boolean Valeur par défaut : false Valeurs possibles : 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 vous recommandons d’actualiser toutes les données chaque semaine afin de vous assurer que vous utilisez 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 oui. 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 targeting_value. Excluez des mots-clés en utilisant le paramètre de requête operator_type défini sur NE. Consultez les types de mots-clés de ciblage pour une description détaillée de chaque type.

Remarque : il n’est possible de cibler qu’un seul segment d’âge par élément de campagne.

Remarque : pour cibler une Custom Audience, cette audience doit être ciblable. C’est-à-dire que targerable doit être égal à true.

Remarque : lorsque vous utilisez le type de ciblage TV_SHOW, il doit y avoir au moins un critère de ciblage LOCATION sur l’élément de campagne avant de définir le ciblage TV_SHOW, et tous les LOCATION doivent se trouver dans la même zone géographique que le TV_SHOW ciblé.

URL de la ressource

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

Paramètres

Nom	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. 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 campagne sur lequel vous agissez dans la requête. Type: string Exemple : 69ob
operator_type required	Spécifie la relation que le critère de ciblage doit avoir. 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 campagne. Les valeurs possibles qui ne sont pas 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 Remarque : il n’est possible de cibler qu’un seul segment AGE par élément de campagne. Les valeurs possibles basées sur des mots-clés incluent : BROAD_KEYWORD, EXACT_KEYWORD, PHRASE_KEYWORD, UNORDERED_KEYWORD Les valeurs possibles pour les Custom Audiences incluent : CUSTOM_AUDIENCE, CUSTOM_AUDIENCE_EXPANDED Valeurs possibles pour les catégories d’App de l’app store installées : APP_STORE_CATEGORY, APP_STORE_CATEGORY_LOOKALIKE Exclusion possible d’app pour Twitter Audience Platform (TAP) : APP_LIST (ne peut être utilisé qu’avec operator_type=NE)
targeting_value required	Spécifie, selon le targeting_type sélectionné, à quel utilisateur, centre d’intérêt, lieu, événement, plateforme, version de plateforme, appareil, mot-clé ou expression, genre, Custom Audience, catégorie d’App store ou exclusion de liste d’apps ce ciblage s’appliquera. Type: string Exemple : 174958347

Exemple de requête

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 la création en lot de nouveaux critères de ciblage avec une seule requête.

Requêtes par lot

• 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 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, en termes de structure, aux points de terminaison correspondants ne traitant qu’un seul élément.

Erreurs de lot

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

URL de ressource

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

Paramètres

Name	Description
operation_type required	Le type d’opération, par élément, en cours d’exécution. Type : enum Valeurs possibles : Create, Delete
params required	Un objet JSON contenant tous les paramètres pour les objets de critères de ciblage. Pour une liste des paramètres requis et facultatifs 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 en cours.

URL de la ressource

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

Paramètres

Name	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: 18ce54d4x5t
targeting_criterion_id required	Référence au critère de ciblage concerné par la requête. Type: string Example: 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": "Custom audience targeting",
        "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
• Conversation
• Appareils
• Événements
• Centres d’intérêt
• Langues
• Lieux
• Opérateurs de réseau
• Versions de 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 de magasins d’applications pour les Produits sponsorisés. Les catégories de magasins d’applications 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 les utilisateurs en fonction des catégories d’applications qu’ils ont installées ou pour lesquelles ils ont indiqué un intérêt.

URL de la ressource

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

Paramètres

Nom	Description
q optional	Requête facultative pour restreindre un critère de ciblage. Omettez ce paramètre pour tout récupérer. Type : string Exemple : music
os_type optional	Restreint les résultats à un magasin d’applications spécifique. Type : enum Valeurs possibles : ANDROID, IOS

Exemple de requête

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

Exemple de réponse

    {
      "data": [
        {
          "name": "Games: Music",
          "targeting_type": "APP_STORE_CATEGORY",
          "targeting_value": "qouq",
          "os_type": "IOS"
        },
        {
          "name": "Music",
          "targeting_type": "APP_STORE_CATEGORY",
          "targeting_value": "qov2",
          "os_type": "IOS"
        }
      ],
      "request": {
        "params": {
          "q": "music",
          "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	Requête facultative pour 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 à tenter de récupérer pour chaque 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

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 les appareils 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

Nom	Description
count optional	Spécifie le nombre d’enregistrements à tenter de récupérer pour chaque requête. Type : int Valeur par défaut : 200 Min, Max : 1, 1000
q optional	Une requête facultative permettant de restreindre les critères 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 (Promoted Products). Un seul événement peut être ciblé par line item.

Remarque : les événements existent souvent sur plusieurs fuseaux horaires, ce qui complique la prise en compte des heures d’événement dans une perspective multi‑fuseaux. Pour simplifier cela, toutes les valeurs start_time et end_time des événements pour cet endpoint sont représenté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 de l’interrogation et de l’utilisation des valeurs start_time et end_time des événements. Par exemple, la fête de l’Indépendance aux États‑Unis est représentée comme start_time=2017-07-04T00:00:00Z et end_time=2017-07-05T00:00:00Z en UTC±00:00, ce qui évite ainsi le problème de l’existence de cette fête sur plusieurs fuseaux horaires au sein des États‑Unis.

Resource URL

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

Parameters

Name	Description
event_types required	Une requête optionnelle permettant de limiter la recherche à 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 à récupérer par requête distincte. Type : int Valeur par défaut : 200 Min, Max : 1, 1000
country_codes optional	Une requête optionnelle permettant de limiter la recherche de critères de ciblage à certains pays via leur 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 au format ISO 8601, à laquelle la campagne se terminera. Type : string Exemple : 2017-10-05T00:00:00Z
start_time optional	L’heure, exprimée au format ISO 8601, à laquelle le line item commencera à être diffusé. Remarque : la valeur par défaut est l’heure actuelle. 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": "New Year's",
          "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 changent rarement ; nous vous recommandons néanmoins d’actualiser cette liste au moins une fois par semaine.

URL de la ressource

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

Paramètres

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

Exemple de requête

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

Exemple de réponse

    {
      "data": [
        {
          "name": "Books and literature/Biographies and memoirs",
          "targeting_type": "INTEREST",
          "targeting_value": "1001"
        }
      ],
      "request": {
        "params": {
          "q": "books",
          "count": 1
        }
      },
      "next_cursor": "6by4n4"
    }

​

GET targeting_criteria/languages

Découvrez les langues disponibles pour le ciblage.

URL de la ressource

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

Paramètres

Nom	Description
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
q optional	Requête facultative permettant de filtrer un critère de ciblage. Omettez ce paramètre pour tout récupérer. Type : string Exemple : english

Exemple de requête

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

Exemple de réponse

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

​

GET targeting_criteria/locations

Découvrez les critères de ciblage géographiques disponibles pour les Promoted Products. Le ciblage géographique est disponible pour les Promoted Accounts et les Promoted Tweets 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 statistiques au niveau du code postal.

Remarque : pour récupérer des villes spécifiques pouvant être ciblées, comme San Francisco ou New York, utilisez l’énumération CITIES avec le paramètre de requête location_type.

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

Resource URL

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

Parameters

Name	Description
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_code optional	Paramètre optionnel permettant de limiter une recherche de critères de ciblage à un pays spécifique avec le code pays ISO à 2 lettres. Omettez ce paramètre pour récupérer des résultats pour tous les pays. Type: string Exemple : JP
cursor optional	Spécifie un curseur pour obtenir la page suivante de résultats. Voir Pagination pour plus d’informations. Type: string Exemple : 8x7v00oow
location_type optional	Limite les résultats à un type de localisation spécifique. Un ciblage plus précis que COUNTRIES peut ne pas être disponible dans toutes les zones géographiques. Type: enum Valeurs possibles : COUNTRIES, REGIONS, METROS, CITIES, POSTAL_CODES
q optional	Paramètre optionnel permettant de limiter une recherche de critères de ciblage. Omettez ce paramètre pour récupérer tous les résultats. Type: string Exemple : New York

Example Request

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

Example Response

    {
      "data": [
        {
          "name": "Los Angeles, Los Angeles CA, CA, USA",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "3b77caf94bfc81fe",
          "targeting_type": "LOCATION"
        },
        {
          "name": "East Los Angeles, Los Angeles CA, CA, USA",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "67571a7baaa5906b",
          "targeting_type": "LOCATION"
        },
        {
          "name": "Lake Los Angeles, Los Angeles CA, CA, USA",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "ea9bfbd43c93400f",
          "targeting_type": "LOCATION"
        },
        {
          "name": "Los Gatos, San Francisco-Oakland-San Jose CA, CA, USA",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "a2de7c70b82b0ca0",
          "targeting_type": "LOCATION"
        },
        {
          "name": "Los Altos, Monterey-Salinas CA, CA, USA",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "6a4364ea6f987c10",
          "targeting_type": "LOCATION"
        },
        {
          "name": "Los Banos, CA, USA",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "b1b6fc646de75904",
          "targeting_type": "LOCATION"
        },
        {
          "name": "Los Alamitos, Los Angeles CA, CA, USA",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "0799ff0a3c1006e9",
          "targeting_type": "LOCATION"
        },
        {
          "name": "Los Angeles, US",
          "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 réseau pour les produits sponsorisés.

Cet endpoint vous permet de rechercher les opérateurs mobiles pouvant être ciblés, tels que AT&T, Verizon, Sprint, T-Mobile, etc., dans plusieurs pays.

URL de la ressource

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

Paramètres

Nom	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
country_code optional	Requête facultative permettant de limiter une 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 Valeur par défaut : US
cursor optional	Spécifie un curseur pour obtenir la page de résultats suivante. Consultez Pagination pour plus d’informations. Type: string Exemple : 8x7v00oow
q optional	Requête facultative permettant de limiter une recherche de critères de ciblage. Omettez ce paramètre pour récupérer tous les résultats. Type: string Exemples : Airpeak

Exemple de requête

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

Exemple de réponse

    {
      "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 en fonction de la version du système d’exploitation mobile pour les produits sponsorisés (Promoted Products). Le ciblage par version de plateforme est disponible pour les comptes sponsorisés (Promoted Accounts) et les Tweets sponsorisés (Promoted Tweets). Cela permet de cibler jusqu’à la version mineure d’un système d’exploitation mobile, comme Android 8.0 ou iOS 10.0.

Resource URL

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

Parameters

Name	Description
q optional	Requête facultative pour restreindre une recherche de critères de ciblage. Omettez ce paramètre pour récupérer tous les résultats. Type : string Exemples : jelly bean

Example Request

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

Example Response

    {
        "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 par plateforme disponibles pour les produits sponsorisés.

URL de la ressource

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

Paramètres

Name	Description
count optional	Indique le nombre d’enregistrements à récupérer par requête distincte. Type: int Valeur par défaut : 200 Min, Max : 1, 1000
q optional	Requête facultative pour restreindre une recherche de critères de ciblage. Omettez ce paramètre pour récupérer tous les résultats. Type: string Exemples : ios, blackberry
lang optional	Utilise un code de langue ISO-639-1. Lorsqu’il est renseigné, un attribut localized_name supplémentaire localisé sera 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": "BlackBerry phones and tablets",
          "targeting_type": "PLATFORM",
          "targeting_value": "2"
        },
        {
          "name": "Mobile web on other devices",
          "targeting_type": "PLATFORM",
          "targeting_value": "3"
        },
        {
          "name": "Desktop and laptop computers",
          "targeting_type": "PLATFORM",
          "targeting_value": "4"
        }
      ],
      "request": {
        "params": {}
      }
    }

​

GET targeting_criteria/tv_markets

Permet de découvrir les marchés TV disponibles où il est possible de cibler des émissions TV. Renvoie les marchés par paramètre de langue (locale) qui peuvent être utilisés pour interroger le point de terminaison GET targeting_criteria/tv_shows.

URL de la ressource

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

Paramètres

Aucun

Exemple de requête

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

Exemple de réponse

    {
      "data": [
        {
          "name": "France",
          "country_code": "FR",
          "locale": "fr-FR"
        },
        {
          "name": "Chile",
          "country_code": "CL",
          "locale": "es-CL"
        },
        {
          "name": "Germany",
          "country_code": "DE",
          "locale": "de-DE"
        },
        {
          "name": "Netherlands",
          "country_code": "NL",
          "locale": "nl-NL"
        },
        {
          "name": "United States",
          "country_code": "US",
          "locale": "en-US"
        },
        {
          "name": "Venezuela",
          "country_code": "VE",
          "locale": "es-VE"
        },
        {
          "name": "Brazil",
          "country_code": "BR",
          "locale": "pt-BR"
        },
        {
          "name": "Mexico",
          "country_code": "MX",
          "locale": "es-MX"
        },
        {
          "name": "Colombia",
          "country_code": "CO",
          "locale": "es-CO"
        },
        {
          "name": "United Kingdom",
          "country_code": "GB",
          "locale": "en-GB"
        },
        {
          "name": "Argentina",
          "country_code": "AR",
          "locale": "es-AR"
        },
        {
          "name": "Japan",
          "country_code": "JP",
          "locale": "ja-JP"
        },
        {
          "name": "Canada",
          "country_code": "CA",
          "locale": "en-CA"
        },
        {
          "name": "Spain",
          "country_code": "ES",
          "locale": "es-ES"
        },
        {
          "name": "Italy",
          "country_code": "IT",
          "locale": "it-IT"
        },
        {
          "name": "United States - Hispanic",
          "country_code": "US",
          "locale": "es-US"
        },
        {
          "name": "Ireland",
          "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 sponsorisés. Le ciblage par émission TV est disponible pour les Tweets sponsorisés sur certains marchés. Consultez le point de terminaison 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 du locale renvoyé par GET targeting_criteria/tv_markets. Type : string Exemple : en-US
count optional	Spécifie le nombre d’enregistrements à récupérer par requête distincte. Type : int Valeur par défaut : 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 Exemple : 8x7v00oow
q optional	Requête optionnelle permettant de restreindre une recherche de critères de ciblage. Omettez ce paramètre pour récupérer tous les résultats. Type : string Exemples : 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 mots-clés ou utilisateurs pour compléter votre sélection initiale.

Resource URL

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

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
suggestion_type required	Spécifiez le type de suggestions à renvoyer. Type : enum Valeurs possibles : KEYWORD, USER_ID
targeting_values required	Ensemble, séparé par des virgules, de mots-clés ou d’ID d’utilisateur utilisé pour alimenter les suggestions. Remarque : ces deux types de suggestions ne peuvent pas être mélangés. Exemple : 756201191646691328
count optional	Spécifie le nombre d’enregistrements à récupérer pour chaque requête distincte. Type : int Valeur par défaut : 30 Min, Max : 1, 50

Example Request

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

Example Response

    {
      "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 required	L’identifiant du compte utilisé. Il apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’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",
        "address_city": "London",
        "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 actuel.

URL de la ressource

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

Paramètres

Nom	Description
account_id obligatoire	L’identifiant du compte concerné. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’Advertiser API, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
address_city facultatif	La ville associée à l’adresse du propriétaire du compte. Type: string Exemple: San Francisco
address_country facultatif	Le code de pays à deux lettres de l’adresse du propriétaire du compte. Type : string Exemple : US
address_email facultatif	L’adresse e-mail associée à l’adresse du titulaire du compte. Type: string Exemple : [e-mail]
address_first_name facultatif	Le prénom indiqué dans l’adresse du propriétaire du compte. Type : string Exemple : API
address_last_name optionnel	Le nom de famille figurant à l’adresse du propriétaire du compte. Type: string Exemple : McTestface
address_name facultatif	Le nom de l’entreprise associé à l’adresse du propriétaire du compte. Type: string Exemple : ABC, Co.
address_postal_code facultatif	Le code postal de l’adresse du propriétaire du compte. Type: string Exemple : 94102
address_region facultatif	La région associée à l’adresse du propriétaire du compte. Type: string Exemple : California
address_street1 facultatif	La première ligne de l’adresse (rue) du propriétaire du compte. Type : string Exemple : 21 March St
address_street2 facultatif	La deuxième ligne de l’adresse du propriétaire du compte. Type: string Exemple : Suite 99
bill_to facultatif	L’entité facturée. Type: enum Valeurs possibles : ADVERTISER, AGENCY
business_relationship facultatif	Indique si le compte appartient à l’annonceur ou à l’agence. Type : enum Valeurs possibles : AGENCY, SELF
client_address_city facultatif	La ville correspondant à l’adresse de l’annonceur. Renseignez ce champ lorsque le compte publicitaire appartient à une agence. Type : string Exemple : Toronto
client_address_country facultatif	Le code pays à deux lettres correspondant à l’adresse de l’annonceur. Renseignez ce champ lorsque le compte publicitaire est détenu par une agence. Type: string Exemple: CA
client_address_email facultatif	L’adresse e-mail associée à l’adresse de l’annonceur. Définissez ce paramètre lorsque le compte publicitaire est détenu par une agence. Type : string Exemple : [e-mail]
client_address_first_name facultatif	Le prénom associé à l’adresse de l’annonceur. Renseignez ce champ lorsque le compte publicitaire appartient à une agence. Type: string Exemple : Brand
client_address_last_name facultatif	Nom de famille associé à l’adresse de l’annonceur. Renseignez ce champ lorsque le compte publicitaire appartient à une agence. Type : string Exemple : Advertiser
client_address_name facultatif	Le nom de l’entreprise associée à l’adresse de l’annonceur. Définissez ce champ lorsque le compte publicitaire appartient à une agence. Type: string Exemple: Brand, Inc.
client_address_postal_code facultatif	Le code postal de l’adresse de l’annonceur. Indiquez ce paramètre lorsque le compte publicitaire appartient à une agence. Type : string Exemple : M5H 2N2
client_address_region facultatif	La région de l’adresse de l’annonceur. Renseignez ce champ lorsque le compte publicitaire appartient à une agence. Type : string Exemple : Ontario
client_address_street1 facultatif	La ligne d’adresse (rue) de l’adresse de l’annonceur. Définissez ce paramètre lorsque le compte publicitaire appartient à une agence. Type : string Exemple : 280 Queen St W
client_address_street2 facultatif	Deuxième ligne de l’adresse de l’annonceur. Définissez ce champ lorsque le compte publicitaire appartient à une agence. Type : string Exemple : The 6
invoice_jurisdiction facultatif	Juridiction de facturation. Type : enum Valeurs possibles : LOI_SAPIN, NONE, NOT_SET
tax_category facultatif	Indique si l’imposition doit être individuelle ou au titre d’une entreprise. Type : enum Valeurs possibles : BUSINESS_NO_VAT, BUSINESS_WITH_VAT, INDIVIDUAL
tax_exemption_id facultatif	ID d’exonération de TVA. Type : string Exemple : 12345
tax_id facultatif	Identifiant d’immatriculation à la TVA. Type : string Valeurs possibles : 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": "London",
        "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": "London",
        "address_country": "GB",
        "address_first_name": null,
        "invoice_jurisdiction": "NOT_SET",
        "address_street2": null,
        "address_email": null
      }
    }

​

Balises de suivi

Lancer dans Postman

​

GET accounts/:account_id/tracking_tags

Récupérer les détails de certaines ou de l’ensemble des balises de suivi associées au compte actuel.

Resource URL

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

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 à tenter de récupérer pour chaque requête distincte. Type : int Valeur par défaut : 200 Min, Max : 1, 1000
cursor optional	Spécifie un curseur pour obtenir la page de résultats suivante. Voir Pagination pour plus d’informations. Type : string Exemple : 8x7v00oow
line_item_ids optional	Limite la réponse uniquement aux balises de suivi associées à des éléments de campagne spécifiques en indiquant une liste d’identifiants séparés par des virgules. Jusqu’à 200 identifiants peuvent être fournis. Type : string Exemple : 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 Exemple : created_at-asc
tracking_tag_ids optional	Limite la réponse uniquement aux balises de suivi souhaitées en indiquant une liste d’identifiants séparés par des virgules. Jusqu’à 200 identifiants peuvent être fournis. Type : string Exemple : 3m82
with_deleted optional	Inclure les résultats supprimés dans votre requête. Type : boolean Valeur 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 définies à 200 toutes les 15 minutes. Type : boolean Valeur par défaut : false Valeurs possibles : true, false

Example Request

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

Example Response

    {
      "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érer 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é. 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
tracking_tag_id required	Une référence à la balise de suivi utilisée dans la requête. Type: string Exemple : 555j
with_deleted optional	Inclure les résultats supprimés dans votre requête. Type: boolean Valeur par défaut : false Valeurs possibles : true, false

Exemple de requête

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 spécifié.

Resource URL

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

Parameters

Nom	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
line_item_id required	Référence à l’élément de campagne avec lequel vous travaillez dans la requête. Type : string Exemple : 8v7jo
tracking_tag_type required	Le type de balise de suivi. Type : enum Valeurs possibles : IMPRESSION_TAG, CLICK_TRACKER
tracking_tag_url required	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

Example Request

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

Example Response

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

Associe une balise de suivi à l’élément de campagne 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 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
tracking_tag_url required	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 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 required	Identifiant du compte exploité. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’Advertiser API, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
tracking_tag_id required	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 utilisateur.

URL de la ressource

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

Paramètres

Name	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
user_id required	Une référence à l’utilisateur que vous utilisez dans 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 par les administrateurs de compte.

URL de la ressource

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

Paramètres

Name	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Exemple : 18ce54d4x5t
user_id required	Une référence à l’utilisateur avec lequel vous opérez dans la requête. Utilisez GET users/lookup pour récupérer un ID utilisateur à partir d’un nom d’écran. Type: long Exemple : 756201191646691328
notification_email optional	Adresse e-mail à utiliser pour les notifications du compte. Type: string Exemple : [e-mail]
contact_phone optional	Numéro de téléphone de contact. Type: string Exemple : 202-555-0128
contact_phone_extension optional	Poste associé à 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": [
              "ACCOUNT_PERFORMANCE",
              "PERFORMANCE_IMPROVEMENT"
            ]
          }
        },
        "data": {
          "notification_email": "[e-mail]",
          "contact_phone": "",
          "Contact_phone_extension": ""
        }
      }