Gestione campagne

​

API per inserzionisti

Programma campagne in modo programmatico e gestisci gli annunci su X tramite questa suite di API.

​

Cosa puoi promuovere?

​

Promoted Ads

• Le Promoted Ads sono annunci ordinari acquistati da inserzionisti che desiderano raggiungere un pubblico più ampio o stimolare l’engagement dei propri follower esistenti.
• Le Promoted Ads sono chiaramente etichettate come Promoted quando un inserzionista paga per la loro collocazione su X. Per il resto, si comportano come normali annunci e possono essere ripostate, commentate, messe “like” e altro ancora. Hanno regole di erogazione tipiche e vengono create usando POST statuses/update.
• “Promoted-only” Tweets, creati tramite POST accounts/:account_id/tweet, possono essere utilizzati nelle campagne di Promoted Tweets ma non verranno mostrati ai follower né appariranno nella timeline pubblica. Per ottenere un elenco di promoted-only tweets per un determinato account, usare GET accounts/:account_id/scoped_timeline.

​

Promoted Accounts

• Le Promoted Accounts fanno parte di Who to Follow, che suggerisce account che gli utenti non seguono attualmente e che potrebbero trovare interessanti. Le Promoted Accounts contribuiscono a far conoscere una gamma ancora più ampia di account che potrebbero piacere alle persone.
• Le Promoted Accounts per la Timeline associano un Promoted Tweet a una campagna di Promoted Account e vengono visualizzate nelle timeline degli utenti.

Le Promoted Trends non sono disponibili nella X Ads API.

​

Campagne e gruppi di annunci (line item)

Le campagne definiscono la pianificazione e il budget di un annuncio. L’inserzionista specifica un budget giornaliero e uno complessivo. La campagna può essere vincolata a un orario di inizio e fine specifici oppure proseguire in modo continuativo fino all’esaurimento del budget. Il budget proviene da uno dei Funding Instrument dell’account pubblicitario. Gli identificatori di campagna (:campaign_id) sono la rappresentazione in base 36 del valore in base 10 mostrato nella X Ads UI.

Gli account pubblicitari sono limitati a un massimo di 200 campagne attive. Questo limite può essere aumentato manualmente fino a 4.000 campagne attive dall’X Account Manager dell’inserzionista su richiesta. Una campagna è considerata attiva finché non raggiunge l’orario di fine o viene eliminata. Le campagne in pausa sono considerate attive fino ai rispettivi orari di fine.

I line item spendono il budget definito da una campagna. I line item raggruppano l’offerta per interazione, il Tweet o l’account da promuovere e le regole di targeting.

​

Analytics

La X Ads API offre una serie di endpoint di analytics per monitorare e ottimizzare le prestazioni delle inserzioni. Consulta Analytics e Analytics Best Practices per maggiori informazioni.

Per la metrica di fatturazione, i data potrebbero non essere definitivi fino a tre giorni dopo l’evento. Prima di tale momento, i data devono essere considerati provvisori. Il valore finale fatturabile sarà sempre inferiore all’importo provvisorio. Il valore fatturabile viene rettificato per lo spam e il traffico correlato di bassa qualità. Vedi Timezones per altre considerazioni relative ai fusi orari.

​

Creazione di una campagna - Procedura passo passo

Il seguente esempio presuppone che tu abbia installato, configurato e autorizzato la tua App e il tuo utente utilizzando twurl. twurl è uno strumento da riga di comando, simile a cURL, che gestisce con efficienza l’autenticazione OAuth di X. twurl è ottimo per testare rapidamente ed effettuare il debug delle funzionalità della X Ads API (e della REST API). Per visualizzare le intestazioni complete della richiesta e della risposta, usa -t per tracciare la chiamata, approssimativamente equivalente all’opzione -v di cURL.

In questo esempio, creeremo una campagna Promoted Ads con targeting per parola chiave.

1. Recupera l’id dell’account.

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

{
  "request": {
    "params": {
    }
  },
  "data": [
    {
      "name": "Account di test per @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. Recupera l’id dello strumento di finanziamento.

Esegui la chiamata all’API GET accounts/:account_id/funding_instruments utilizzando l’id dell’account ottenuto nel comando precedente.

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. Crea una campagna e associarla allo strumento di finanziamento.

Specifica l’ora di inizio e il budget per la campagna. In questo esempio utilizzeremo un budget di 500 $e un limite giornaliero di 50$.

twurl -H ads-api.x.com -d "funding_instrument_id=yyyy&name=La mia prima campagna&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": "La mia prima campagna",
    "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": "La mia prima campagna",
      "total_budget_amount_local_micro": 500000000
    }
  }
}

4. Crea una line item associata alla campagna.

Ora che disponiamo di un id di campagna, possiamo creare una line item da associarle. La line item include il prezzo dell’offerta, il targeting e la componente creativa effettiva della campagna. Per questa line item, promuoveremo tweet con un’offerta di 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": "Senza titolo",
    "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. Crea un profilo di targeting associato al line item.

Con il line item creato, possiamo assegnare i criteri di targeting. Vogliamo targetizzare la frase chiave “grumpy cat” nell’area della San Francisco Bay Area. Questo richiederà una ricerca dell’id della località e due richieste POST a 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. Infine, riattiva il line item.

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

Ecco fatto! Ora la nostra campagna Promoted Tweets in Timelines è attiva, mirata, finanziata e in esecuzione.

​

Campagne basate sugli obiettivi

Le campagne e la tariffazione basate sugli obiettivi consentono agli inserzionisti di pagare per le azioni in linea con i loro obiettivi di marketing. Per abilitarle, imposta l’objective appropriato sulle line item.

Il parametro utilizzato sugli endpoint di scrittura delle line item e restituito sugli endpoint di lettura è objective. Attualmente, questo campo può assumere i seguenti valori:

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

Gli obiettivi influiscono su come ottimizziamo le campagne nelle nostre aste e su come le fatturiamo. Offriamo una tariffazione basata sull’obiettivo, ad esempio CPAC per APP_ENGAGEMENTS, CPAC o CPI per APP_INSTALLS, CPLC per WEBSITE_CLICKS, CPF per FOLLOWERS, CPE per ENGAGEMENTS e CPM per REACH.

Le campagne di promozione di app per dispositivi mobili devono includere l’obiettivo APP_ENGAGEMENTS o APP_INSTALLS.

Nota: Non sono consentite line item con obiettivi diversi all’interno della stessa campagna.

Obiettivo della campagna	Obiettivo API	Media nei Tweet	Modello di prezzo
Re‑engagement dell’app	APP_ENGAGEMENTS	Scheda di download dell’app con immagine o video obbligatoria.	CPAC
Installazioni dell’app	APP_INSTALLS	Scheda di download dell’app con immagine o video obbligatoria.	CPAC o CPI (impostato con charge_by)
Reach	REACH	Nessuna restrizione.	CPM
Followers	FOLLOWERS	Tweet non obbligatorio ma consigliato. Nessuna restrizione sui media nei Tweet per le campagne Followers, anche se consigliamo Tweet solo testo. Ulteriori informazioni	CPF
Engagement	ENGAGEMENTS	Nessuna restrizione.	CPE
Visualizzazioni video	VIDEO_VIEWS	Scheda conversazionale video, video o GIF obbligatori.	CPV o costo per visualizzazione 3s/100%
Visualizzazioni pre‑roll	PREROLL_VIEWS	Video obbligatorio.	CPV o costo per visualizzazione 3s/100%
Clic sul sito web	WEBSITE_CLICKS	Scheda sito web consigliata ma non obbligatoria. Il Tweet deve includere una scheda sito web oppure un link al sito (non entrambi).	CPLC

​

Strumenti di finanziamento

Gli strumenti di finanziamento sono la fonte del budget della campagna. Gli strumenti di finanziamento non possono essere creati tramite la X Ads API; devono essere già configurati dal responsabile dell’account dell’inserzionista presso X (per le linee di credito) o tramite ads.x.com (per le carte di credito) per poter essere utilizzati.

Per ottenere l’elenco di tutti i funding_instruments su un account, consultare GET accounts/:account_id/funding_instruments e GET accounts/:account_id/funding_instruments/:funding_instrument_id per i dettagli di uno specifico.

​

Attributi dello strumento di finanziamento

Descrittivi: account_id, id dello strumento di finanziamento, type dello strumento di finanziamento, description e io_header (ID dell’intestazione dell’insertion order). Nota che un singolo io_header può essere associato a più strumenti di finanziamento.

Capacità di finanziamento: able_to_fund e reasons_not_able_to_fund.

Tempo: created_at, updated_at, start_time e end_time rappresentati come stringa, formattata come “%Y-%m-%dT%l:%M:%S%z”.

Stato booleano: paused, deleted e cancelled (true o false).

Finanziari: currency (formato ISO-4217), credit_limit_local_micro, credit_remaining_local_micro e funded_amount_local_micro. Il valore di una valuta è rappresentato in micro-unità. Per USD, $5,50 è codificato come 5.50*1e6, cioè 5.500.000. Per rappresentare un “valore intero”, è necessario moltiplicare il valore in micro locale per 1e6 (1_000_000) per tutte le valute.

​

Dettagli degli attributi

credit_limit_local_micro è valido solo per strumenti di finanziamento con type CREDIT_CARD o CREDIT_LINE e rappresenta il limite di credito per tale strumento.

funded_amount_local_micro è valido solo per strumenti di finanziamento con type INSERTION_ORDER e rappresenta il budget assegnato.

credit_remaining_local_micro è valido per strumenti di finanziamento con type CREDIT_LINE e AGENCY_CREDIT_LINE. Rappresenta credit_limit_local_micro meno l’importo già speso su quello strumento di finanziamento. Non rappresenta la differenza tra funded_amount_local_micro e l’importo speso. Distinguiamo tra limite di credito e importo finanziato perché corrispondono a diversi metodi di finanziamento sottostanti e ad accordi di spesa distinti che abbiamo con gli inserzionisti.

​

Tipi di strumenti di finanziamento

Carte di credito

In genere utilizzate dagli inserzionisti self-serve (senza account manager).

Linee di credito

Sono sotto forma di insertion order (IO) e vengono impostate dagli account manager.

Linee di credito multi-handle

Gli inserzionisti possono finanziare campagne su più handle con questo tipo di linea di credito. Questa funzionalità viene abilitata dal loro X Account Manager, associando i diversi @handle a una specifica linea di credito.

Ad esempio, sia @NikeSB sia @NikeFuel possono avere accesso alla linea di credito @Nike. Questo strumento di finanziamento è disponibile come qualsiasi altro. I data si recuperano inviando una richiesta GET all’endpoint funding_instrument. Ecco un esempio di risposta (nota il tipo 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 - Linea di credito",
            "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
}

L’unica particolarità di questo strumento di finanziamento è il campo type e il fatto che sia disponibile per tutti gli account a esso associati. Naturalmente, il credito residuo è influenzato da tutte le campagne finanziate da questo strumento, in tutti gli account che lo condividono. I dettagli su quali account siano associati a una specifica linea di credito non sono disponibili tramite l’API (né tramite ads.x.com).

Per ulteriori informazioni sulle enumerazioni dei Funding Instrument, fare clic qui.

​

Targeting

Il targeting è un concetto fondamentale della X Ads API. Il targeting viene impostato a livello di line item e le opzioni variano in base al placement. Per definire nuovi criteri di targeting, utilizza POST accounts/:account_id/targeting_criteria e PUT accounts/:account_id/targeting_criteria per aggiornarli.

Usa GET accounts/:account_id/line_items per ottenere l’elenco di tutti i line item e GET accounts/:account_id/line_items/:line_item_id per recuperare un line item specifico.

​

Opzioni di targeting per placement

I prodotti Promoted Tweets e Promoted Accounts possono essere disponibili in una varietà di placement. Promoted Trends (PTr) non sono disponibili tramite l’API.

Per le possibili combinazioni di placement, consulta l’endpoint GET line_items/placements. Ogni placement offre opzioni di targeting differenti. Località, Piattaforma e Genere sono disponibili per tutti. Le altre opzioni dipendono dal tipo di placement.

• X Search: Targeting per età, Dispositivi, Eventi, Genere, Tipi di keyword (tutti), Lingua, Località, Attivazione rete, Operatori di rete, Piattaforma, Versione della piattaforma, Pubblici personalizzati, Solo Wi‑Fi
• X Timeline: Targeting per età, Dispositivi, Eventi, Follower di, Simili ai follower di, Genere, Interessi, Lingua, Località, Attivazione rete, Operatori di rete, Tipi di keyword non esatti, Tipi di pubblico partner, Piattaforma, Versione della piattaforma, Tipi di retargeting, Pubblici personalizzati, Tipi di targeting TV, Solo Wi‑Fi
• X Profiles & Tweet Details: Targeting per età, Dispositivi, Eventi, Follower di, Simili ai follower di, Genere, Interessi, Lingua, Località, Attivazione rete, Operatori di rete, Tipi di keyword non esatti, Tipi di pubblico partner, Piattaforma, Versione della piattaforma, Tipi di retargeting, Pubblici personalizzati, Tipi di targeting TV, Solo Wi‑Fi

​

Comprendere i tipi di targeting

Targeting per età: Targetizza gli utenti in base a specifici intervalli di età. Un elenco degli enum degli intervalli di età è disponibile nella pagina Enumerations.

Eventi: Specifica un evento per il targeting. È possibile utilizzare un solo evento per il targeting (per line item). Usa l’endpoint GET targeting_criteria/events per trovare gli eventi disponibili per il targeting.

Genere: Targetizza uomini (1) o donne (2). Lascia null per targetizzare tutti.

Categorie dell’App Store installate: Usa questo tipo di targeting per targetizzare gli utenti in base alle categorie delle app che hanno installato o per cui hanno manifestato interesse. Vedi GET targeting_criteria/app_store_categories.

Interessi: Targetizza gli utenti per interesse. Ottieni l’elenco degli interessi da GET targeting_criteria/interests. Puoi targetizzare fino a 100 interessi.

Follower di: Targetizza i follower di qualsiasi utente completamente promuovibile per l’account corrente (nota: attualmente il titolare principale dell’account è l’unico utente completamente promuovibile di quell’account). GET accounts/:account_id/promotable_users per ottenere un elenco di utenti promuovibili.

Simili ai follower di: Targetizza persone con gli stessi interessi dei follower di utenti specifici. Puoi usare fino a 100 Users.

Località: Specifica fino a 2.000 località da targetizzare. Ottieni l’elenco da GET targeting_criteria/locations. Esistono requisiti aggiuntivi per gli annunci che targetizzano determinati paesi. Consulta Country Targeting and Display Requirements per ulteriori informazioni.

Parole chiave: Le opzioni di targeting per parole chiave variano in base al tipo di posizionamento. Puoi utilizzare fino a 1000 parole chiave per il targeting (per line item). Consulta la sezione Tipi di parola chiave per le opzioni.

Targeting per lingua: Targetizza gli utenti che comprendono lingue specifiche.

Targeting per operatore di rete mobile: Consente agli inserzionisti di targetizzare gli utenti in base all’operatore mobile, usando il tipo di targeting NETWORK_OPERATOR da GET targeting_criteria/network_operators.

Targeting per nuovi dispositivi mobili: Raggiungi gli utenti in base alla data in cui hanno effettuato per la prima volta l’accesso a X tramite il loro dispositivo, utilizzando il tipo di targeting NETWORK_ACTIVATION_DURATION con operator_type pari a LT per minore di e GTE per maggiore o uguale.

Piattaforme, Versioni della piattaforma, Dispositivi e Solo WiFi: Consente il targeting dei dispositivi mobili lungo diverse dimensioni. Piattaforme è un tipo di targeting di alto livello che può coprire categorie ampie di telefoni. Esempi di valori sono iOS e Android. I dispositivi consentono di targetizzare gli utenti di specifici dispositivi mobili, ad esempio iPhone 5s, Nexus 4 o Samsung Galaxy Note. Le versioni della piattaforma consentono di targetizzare gli utenti di versioni di specifici sistemi operativi mobili, fino alla point release. Esempi includono iOS 7.1 e Android 4.4. Solo WiFi consente di targetizzare solo gli utenti che utilizzano i loro dispositivi su una rete WiFi; se questo non è impostato, saranno targetizzati sia gli utenti che usano la connessione dell’operatore sia il WiFi.

• Gli utenti possono targetizzare piattaforme e dispositivi se non c’è sovrapposizione. Posso targetizzare BlackBerry come piattaforma e iPad Air come dispositivo contemporaneamente.
• Gli utenti possono targetizzare dispositivi e versioni del sistema operativo contemporaneamente. Posso targetizzare iPad Air e iOS >= 7.0.
• Gli utenti non possono targetizzare piattaforme più ampie dei dispositivi. Non posso targetizzare iOS e iPad Air.

[Tailored Audiences]/x-ads-api/audiences: Raggiungi gli utenti tramite un partner pubblicitario approvato per indirizzare gruppi di clienti e connetterti con loro su X.

TV Targeting

TV Show Targeting: raggiungi le persone che interagiscono con specifici programmi TV. Questo criterio di targeting può essere configurato per rimanere attivo per tutta la durata della campagna con il tipo di targeting TV_SHOW. Usa gli endpoint GET targeting_criteria/tv_markets e GET targeting_criteria/tv_shows per determinare i programmi TV disponibili.

Tweet Engager Retargeting

Il retargeting dei tweet engager consente agli inserzionisti di raggiungere pubblici su più dispositivi che in precedenza sono stati esposti o hanno interagito con i loro Tweet promossi o organici su X. Con questo targeting gli inserzionisti possono ricontattare le persone che hanno visto o interagito con i contenuti su X e che hanno maggiori probabilità di interagire ulteriormente o convertire con messaggi o offerte successive. Gli utenti diventano idonei al targeting entro pochi minuti dall’esposizione o dall’interazione e rimangono idonei fino a 90 giorni per le interazioni e 30 giorni per le esposizioni.

Tipi di targeting Tweet Engager:

• ENGAGEMENT_TYPE, che accetta come valore di targeting IMPRESSION o ENGAGEMENT. Specifica se desideri raggiungere utenti esposti (IMPRESSION) o utenti che hanno interagito (ENGAGEMENT).
• CAMPAIGN_ENGAGEMENT usa un id campagna come valore di targeting. Verranno raggiunti gli utenti che hanno interagito con o sono stati esposti a questa campagna (in base a ENGAGEMENT_TYPE).
• USER_ENGAGEMENT, che usa l’id dell’utente promosso come valore di targeting per raggiungere gli utenti che sono stati esposti o hanno interagito con i contenuti organici di un inserzionista (in base a ENGAGEMENT_TYPE). Deve trattarsi dell’id dell’utente promosso associato all’account Ads.

Note: ENGAGEMENT_TYPE è obbligatorio, oltre ad almeno un valore valido tra CAMPAIGN_ENGAGEMENT o USER_ENGAGEMENT. Entrambi i tipi di targeting dei tweet engager possono essere presenti e più campagne possono essere incluse nella stessa voce di riga.

Video Viewer Targeting: Il targeting dei video viewer si basa sul targeting dei tweet engager e consente agli inserzionisti di raggiungere pubblici che in precedenza hanno guardato in parte o per intero un video su X. Gli inserzionisti possono indirizzare video organici, video promossi o entrambi. I video promossi non sono limitati a campagne o voci di riga con obiettivo visualizzazioni video.

Tipi di targeting Video Viewer:

• VIDEO_VIEW per gli utenti che hanno cliccato per riprodurre il video o hanno visto 3 secondi di riproduzione automatica
• VIDEO_VIEW_PARTIAL per gli utenti che hanno visto il 50% del video
• VIDEO_VIEW_COMPLETE per gli utenti che hanno visto almeno il 95% del video

Come per il targeting dei tweet engager, quando si utilizza ENGAGEMENT_TYPE nei criteri di targeting della voce di riga deve essere presente uno o entrambi i seguenti elementi:

• CAMPAIGN_ENGAGEMENT usa un id campagna come valore di targeting. Verranno raggiunti gli utenti che hanno guardato un video (in base a ENGAGEMENT_TYPE) in questa campagna.
• USER_ENGAGEMENT, che usa l’id dell’utente promosso come valore di targeting per raggiungere gli utenti che hanno guardato un video (in base a ENGAGEMENT_TYPE) nei contenuti organici di un inserzionista. Deve trattarsi dell’id dell’utente promosso associato all’account Ads.

Tipi di keyword

Consulta il nostro documento di supporto sul keyword targeting per una panoramica concettuale.

• Broad (valore predefinito): corrisponde a tutte le parole, indipendentemente dall’ordine. Non è sensibile a maiuscole, plurali o tempi verbali. Verrà automaticamente ampliata quando possibile (ad es. “car repair” corrisponderebbe anche a “automobile fix”). Se vuoi indirizzare senza espansione, aggiungi un segno + prima delle keyword, per esempio “+boat +jet”. L’uso di keyword senza il + corrisponde al Broad Match.
• Unordered (deprecato): corrisponde a tutte le parole, indipendentemente dall’ordine. Non è sensibile a maiuscole, plurali o tempi verbali.
• Phrase: corrisponde esattamente alla stringa di keyword; possono essere presenti altre keyword.
• Exact: corrisponde esattamente alla stringa di keyword, e non ad altre.
• Negative: evita di corrispondere a ricerche che includono tutte queste keyword in qualsiasi punto della query, indipendentemente dall’ordine, anche se sono presenti altre parole.
• Negative Phrase: evita di corrispondere a ricerche che includono questa esatta stringa di keyword in qualsiasi punto della query, anche se sono presenti altre parole.
• Negative Exact: evita di corrispondere a ricerche che corrispondono esattamente a queste keyword e non contengono altre parole.  

Emoji targeting

Il targeting tramite emoji è supportato attraverso il targeting per parola chiave. Per utilizzare il targeting con emoji, crea semplicemente un targeting per parola chiave usando i codepoint Unicode che rappresentano quell’emoji, ad esempio U+1F602 (xF0x9Fx98x82 in UTF-8) per l’emoji “face with tears of joy” (😂). Le emoji supportate possono essere verificate nell’elenco twemoji. Il targeting di un’emoji include tutte le varianti.

Per un riepilogo di tutti i valori con indicazione dei campi obbligatori/opzionali e i dettagli specifici per ciascuno, consulta PUT accounts/:account_id/targeting_criteria.

​

Combinazioni dei criteri di targeting

Flusso di lavoro della campagna aggiornato

Crea campagne con targeting ampio basato su criteri di area geografica, genere, lingua e dispositivo/piattaforma. Gli inserzionisti possono quindi combinare il targeting ampio con ulteriori criteri di targeting (ad es. interessi, parole chiave, follower, tailored audiences, TV). Se per una riga non viene specificato alcun criterio di targeting, tale riga raggiungerà tutti gli utenti a livello mondiale.

Tipi “primari”	Altri tipi
Follower	Località
Tailored Audiences	Genere
Interests	Lingue
Keywords	Dispositivi e piattaforme
TV	Età

I criteri di targeting verranno combinati per il tuo gruppo di annunci come segue:

• I tipi di targeting “primari” verranno uniti con ∪ (ossia in un’unione logica).
• Gli altri tipi di targeting verranno combinati con AND.
• I medesimi tipi verranno combinati con OR.

Alcuni esempi

A colpo d’occhio: [(Followers) ∪ (Tailored Audiences) ∪ (Interests) ∪ (Keywords)] AND (Location) AND (Gender) AND (Languages) AND (Devices and Platforms)

Un esempio geografico:

Supponiamo di voler definire per un gruppo di annunci della nostra campagna il seguente targeting:

• utenti di X negli Stati Uniti, in Inghilterra e in Canada (Location)
• che siano donne (Gender)
• derivati da una lista di Tailored Audiences (“Primary”)
• con Keywords (“Primary”)

I criteri di targeting saranno:

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

​

Esempi aggiuntivi

• Seleziona Genere e Geo ma senza primario: (Male) AND (US OR GB)
• Seleziona Genere, Geo, Interessi: (Female) AND (CA) AND (Computers OR Technology OR Startups)
• Seleziona Genere, Geo, Interessi, Tailored Audiences, Keywords: (Male) AND (GB) AND (Cars ∪ Tailored Audiences for CRM ∪ autocross)

​

Pianificazione del budget

Gli inserzionisti ora hanno un controllo maggiore sulla velocità con cui i budget giornalieri vengono spesi per le campagne di Tweet e Account promossi. Abilitare la distribuzione standard, impostazione predefinita, garantisce un ritmo di spesa uniforme nell’arco della giornata.

Disattivando la distribuzione standard, erogheremo impression e genereremo interazioni il più rapidamente possibile fino all’esaurimento del budget giornaliero, che potrebbe avvenire molto presto nella giornata a seconda del targeting e della concorrenza. Questo è chiamato distribuzione accelerata.

Per iniziare

La distribuzione standard è l’opzione predefinita per tutte le campagne, quindi non è necessaria alcuna azione a meno che non si desideri disattivarla. Per spendere il budget giornaliero di una campagna il più rapidamente possibile, imposta il parametro standard_delivery su false per passare alla distribuzione accelerata (vedi GET accounts/:account_id/campaigns).

Note

• Il “giorno” fa riferimento al fuso orario dell’account inserzionista di X (es. America/Los_Angeles).
• I primi risultati indicano che la distribuzione standard migliora eCPE/CPF per gli inserzionisti, con una copertura più coerente nell’arco della giornata.

Per ulteriori informazioni su budget e pacing, consulta le FAQ su offerte e aste.

​

Offerte mirate

Gestione campagne

​

Strategia di offerta

Abbiamo introdotto il concetto di strategia di offerta per semplificare il flusso di creazione delle campagne e ridurre la confusione sulle combinazioni di più parametri.

Tutte le precedenti combinazioni di parametri (contrassegnate come legacy) possono essere ottenute impostando un parametro di obiettivo equivalente. Ulteriori informazioni sono disponibili nell’annuncio qui.

Ad esempio:

Obiettivo della campagna	Legacy	X 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 (Nota: bid_unit non era necessario per alcuni obiettivi di campagna)	bid_strategy = TARGET

​

Offerta a target

Con l’offerta a target puoi indicare un costo obiettivo che desideri pagare e la piattaforma X Ads ottimizzerà la tua campagna per le performance restando in prossimità o al di sotto del costo indicato.

Questa funzionalità ti offre la flessibilità di raggiungere utenti con elevata probabilità di compiere l’azione desiderata (ad esempio un clic su un link, una lead o un follow) mantenendo il controllo dei costi. È una funzionalità potente per gli inserzionisti che desiderano più opzioni per la configurazione e l’ottimizzazione della campagna (incluse le opzioni di offerta).

Per le line item con obiettivi di campagna compatibili, abbiamo introdotto un nuovo meccanismo di pricing per l’importo dell’offerta che consente di specificare un costo obiettivo. La nostra piattaforma pubblicitaria effettua dinamicamente offerte per tuo conto per aiutarti a ottenere più risultati, lavorando per mantenere il costo medio entro il 20% del target specificato. L’impostazione bid_strategy sulle line item può essere valorizzata con TARGET per abilitare l’offerta a target sugli obiettivi di campagna pertinenti, come:

• WEBSITE_CLICKS
• WEBSITE_CONVERSIONS
• APP_INSTALLS
• APP_ENGAGEMENTS
• REACH

​

Requisiti di targeting e di visualizzazione per paese

Gestione delle campagne

In questa pagina sono riportati i requisiti di targeting e di visualizzazione specifici per paese. Tutti i partner devono attenersi a tali requisiti.

​

Russia

Le Ads Policies di X vietano agli inserzionisti di indirizzare la Russia con annunci che non siano in lingua russa. Quando i tuoi utenti prendono di mira specificamente la Russia, devi mostrare il seguente messaggio di avviso ai tuoi utenti:

Gli annunci rivolti alla Russia devono essere in lingua russa.

​

Strumenti di finanziamento gestiti dal partner

Il flusso di onboarding configura un account ads.x.com per l’account X, gestibile dal partner tramite la X Ads API, i cui costi pubblicitari vengono addebitati al partner.  

​

Configurazione iniziale del partner

Il processo per configurare un nuovo partner PMFI Ads API richiede fino a 3 settimane dal momento dello scambio delle informazioni necessarie. È necessario condividere quanto segue con i contatti tecnici di X, nonché con il referente X che gestisce l’integrazione con il partner, per avviare il processo:

• Il partner deve condividere la propria chiave pubblica PGP/GPG. È necessario scambiare una chiave segreta condivisa tra il partner Ads API e X. Questa verrà utilizzata per verificare i dati durante il flusso di onboarding.
• L’ app_id o il consumer_secret per la X App che verrà utilizzata per l’accesso alla X Ads API. Puoi visualizzare e modificare le X App esistenti tramite la dashboard dell’App se hai effettuato l’accesso al tuo account X su developer.x.com. Se devi creare una X App, dovrai disporre di un account sviluppatore approvato. X consente una App per produzione+sandbox e un’App facoltativa per il solo accesso sandbox. La X App deve essere creata su un handle X aziendale, controllato dal partner.  

​

Flusso di onboarding dell’inserzionista

Il flusso di onboarding dell’inserzionista avviene tramite browser nel modo seguente:

1. L’utente avvia il flusso di onboarding sul sito del partner e inserisce l’handle che desidera sottoporre a onboarding.
2. Il partner reindirizza l’utente a un URL su ads.x.com con un payload firmato. Questo payload contiene l’app_id dell’API del partner, lo X user_id dell’handle X da sottoporre a onboarding, un URL di callback e altri fields documentati di seguito.
3. All’utente viene richiesto di accedere a ads.x.com utilizzando la pagina di accesso standard di x.com.
4. Una volta effettuato l’accesso, viene avviato il processo di onboarding. Questo passaggio include la revisione degli annunci, la convalida dell’account e altri controlli.
5. Quando tutte le attività di onboarding sono completate, l’utente viene reindirizzato all’URL di callback fornito dal partner della X Ads API, con un payload che indica esito positivo o negativo. Questo include il processo di autorizzazione a 3 leg.  

​

Payload di reindirizzamento per l’onboarding

URL per il reindirizzamento:

https://ads.x.com/link_managed_account

L’URL di reindirizzamento sarà chiamato con i seguenti parametri:

Nome	Tipo	Descrizione
callback_url	stringa codificata in URL	l’utente verrà reindirizzato a questo URL al termine del processo di collegamento dell’account, indipendentemente dall’esito. Vedere la sezione sull’URL di reindirizzamento del partner per i dettagli del protocollo
client_app_id	integer	id dell’App client della X API, utilizzato per identificare il partner gestore
promotable_user_id	integer	user_id di X dell’@handle le cui promozioni devono essere gestite dal partner gestore. Utilizzato per assicurarsi che corrisponda all’utente che accede a ads.x.com per completare il processo di collegamento
fi_description	String codificata in URL (max 255 caratteri)	nome dello strumento di finanziamento. Sarà mostrato nel campo di descrizione nell’API quando lo strumento di finanziamento viene recuperato. Se viene fornita una descrizione per il funding_instrument, il funding_instrument esistente verrà messo in pausa e verrà configurato un nuovo strumento di finanziamento del partner gestito (se ne esiste già uno con lo stesso nome, non accadrà nulla)
timezone	String, in formato Area/Location	Fuso orario utilizzato per determinare il giorno a cui si applicano i budget giornalieri e in cui verranno aggregate le spese
currency	Codice valuta ISO 4217	Valuta utilizzata per inserire le offerte e in cui verranno fatturate le spese
country	Codice paese ISO 3166-1 alpha 2	Paese di fatturazione dell’account
signature	Codice binario codificato in URL e in base64, come spiegato di seguito	firma che combina un segreto condiviso e gli altri parametri per verificare l’autenticità della chiamata e la validità dei parametri.

​

Payload dell’URL di callback

L’URL di reindirizzamento di base è fornito tramite il parametro callback_url nella richiesta di collegamento dell’account (vedi sopra). I parametri aggiunti da ads.x.com sono:

Nome	Tipo	Descrizione
status	string	OK è stato creato un account oppure è stato trovato un account esistente idoneo. ACCOUNT_INELIGIBLE se non sono soddisfatti i vincoli specifici del partner USER_MISMATCH l’account X utilizzato per accedere a ads.x.com era diverso dal promotable_user_id nella richiesta di collegamento dell’account INCOMPLETE_SERVING_BILLING_INFO fuso orario, valuta o paese non specificati INVALID_COUNTRY è stato fornito un valore di paese non valido INVALID_CURRENCY è stato fornito un valore di valuta non valido INVALID_TIMEZONE è stato fornito un valore di fuso orario non valido
account_id	string codificata in URL	id dell’account pubblicitario X dell’account collegato
funding_instrument_id	string codificata in URL	id dello strumento di finanziamento gestito dal partner attivo
signature	codice binario codificato in URL e in base64, come spiegato di seguito	Firma HMAC-SHA1 codificata in Base64 che combina un segreto condiviso e gli altri parametri per verificare l’autenticità della chiamata, nonché la validità dei parametri. Per assicurarsi che la callback URL sia valida solo per l’X user_id a cui era destinato il processo di collegamento dell’account, l’X user_id deve essere aggiunto al segreto condiviso (utilizzando &) quando si firma la richiesta.

Per assicurarsi che la callback URL sia valida solo per l’X user_id a cui era destinato il processo di collegamento dell’account, l’X user_id deve essere aggiunto al segreto condiviso (utilizzando &) quando si firma la richiesta.  

​

Firma della richiesta e degli URL di callback

Per garantire che le richieste a /link_managed_account e l’URL di callback siano valide, devono essere firmate all’origine e verificate dal destinatario prima che quest’ultimo vi dia seguito. Firmare la richiesta con un segreto condiviso tra X e il partner responsabile garantisce che ciascuna parte accetti solo richieste inviate dalla controparte autorizzata.

L’algoritmo di generazione della firma è simile a quello utilizzato in OAuth.

Crea una stringa base della firma come segue:

• Converti il metodo HTTP in maiuscolo e imposta la stringa base uguale a questo valore.
• Aggiungi il carattere ‘&’ alla stringa base.
• Applica la percent-encoding all’URL (senza parametri) e aggiungilo alla stringa base.
• Aggiungi il carattere ‘&’ alla stringa base.
• Aggiungi la query string percent-encoded, costruita come segue:
• Applica la percent-encoding a ogni chiave e valore che dovranno essere firmati.
• Ordina l’elenco dei parametri alfabeticamente per chiave.
• Per ogni coppia chiave/valore (e includendo primary_promotable_user_id per l’URL di reindirizzamento del partner):
• Aggiungi la chiave percent-encoded alla query string.
• Aggiungi il carattere ‘=’ alla stringa base.
• Aggiungi il valore percent-encoded alla query string.
• Separa le coppie chiave=valore percent-encoded con il carattere ‘&’.
• Usa l’algoritmo HMAC-SHA1, utilizzando come chiave il segreto condiviso precedentemente scambiato e come valore la stringa base, per generare la firma.
• Codifica in Base64 l’output del passaggio precedente, elimina il carattere di newline finale, applica la percent-encoding alla firma generata e aggiungila all’URL in un parametro signature  

​

Esempi di firma

Firma di una richiesta di collegamento dell’account

URL da firmare, assumendo una richiesta 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

Questo URL contiene i seguenti parametri:

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

La stringa di base, composta dal metodo HTTP e dall’URL senza parametri, passaggi da a a d, è la seguente:

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

La query string, prodotta dai sottopassi del punto e, è la seguente:

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

Nota che le coppie chiave-valore sono ordinate per nome della chiave.

La query string con percent-encoding è la seguente:

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

La stringa di base completa, combinando i passaggi da a a d ed 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

Utilizzando l’algoritmo hmac-sha1, firmeremo questa stringa con la parola “secret” come chiave. Il risultato è codificato in Base64 e presentato senza il “\n” finale (passaggi 2 e 3): KBxQMMSpKRrtg9aw3qxK4fTXvUc=

Questa firma viene quindi aggiunta (con percent-encoding) alla fine dell’URL originale nel parametro signature (passaggio 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

Firma di un URL di reindirizzamento del partner (callback della richiesta di collegamento account) L’URL da firmare, assumendo una richiesta GET:

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

Questo URL contiene i seguenti parametri:

account_id = ABC, funding_instrument_id = DEF e status = OK

La stringa di base, composta dal metodo HTTP e dall’URL senza parametri, passaggi da a a d, è la seguente:

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

La query string, prodotta dai sottopassi del punto e, è la seguente:

account_id=ABC&funding_instrument_id=DEF&status=OK

La query string con percent-encoding è la seguente:

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

La stringa di base completa, combinando i passaggi da a a d ed e:

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

Utilizzando l’algoritmo hmac-sha1, firmeremo questa stringa con la parola “secret” e l’id utente X per cui è stata effettuata la richiesta di collegamento originale, 1 (promotable_user_id = 1 sopra), come chiave: “secret&1”.

Il risultato è codificato in Base64 e presentato senza il “\n” finale (passaggi 2 e 3): jDSHDkHJIFXpPLVxtA3a9d4bPjM=

Questa firma viene quindi aggiunta (percent-encoded) alla fine dell’URL originale nel parametro signature (passaggio 4):

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

​

Utilizzo/rinnovo della chiave condivisa

L’algoritmo di firma dovrebbe poter essere eseguito con più chiavi. Ciò consente l’uso di chiavi condivise multiple e permette di ruotarle periodicamente.  

​

creazione di partner_managed_funding_instrument

Se viene fornito il parametro fi_description e non esiste alcun partner_managed_funding_instrument con lo stesso nome nell’account, verrà creato un nuovo partner_managed_funding_instrument e tutti i partner_managed_funding_instrument esistenti verranno messi in pausa.

Se esiste un partner_managed_funding_instrument con lo stesso nome, non ne verrà creato uno nuovo.  

​

Ripetizione delle chiamate al flusso di onboarding / aggiornamento del token

Il flusso di onboarding può essere ripetuto nel caso in cui l’access token dell’API sia stato smarrito. L’implementazione del flusso di onboarding richiede che l’utente sia autenticato. Se l’utente corrisponde al promotable_user_id, l’account pubblicitario associato viene trovato e tutto risulta corretto, l’utente verrà reindirizzato all’URL di callback e il partner potrà avviare il flusso OAuth per ottenere un access token.  

​

Flusso di errore non reindirizzabile

Se l’URL di collegamento dell’account viene richiamato con parametri non validi, all’utente verrà mostrata una pagina simile a quella visualizzata nel flusso OAuth quando i parametri sono non validi o scaduti.  

​

Aggiornamenti in corso al PMFI

Dopo l’onboarding dell’inserzionista, lo strumento di finanziamento può essere gestito tramite l’endpoint PUT accounts/:account_id/funding_instruments/:funding_instrument_id esclusivamente dal partner che lo amministra.

​

Posizionamenti

Esistono diversi punti in cui gli annunci su X possono essere visualizzati. Questo si imposta a livello di line item usando il parametro placements. I valori possibili sono:

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

Il product_type e l’objective del line item determinano quali posizionamenti sono consentiti. L’endpoint GET line_items/placements può essere utilizzato per recuperare le opzioni di posizionamento valide per ciascun tipo di prodotto.

Inoltre, la tabella seguente elenca le combinazioni valide di posizionamento e obiettivo.

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

Nota: Non è possibile specificare solo il posizionamento TWITTER_PROFILE.

Nota: TWITTER_SEARCH richiede il keyword targeting.

Nota: L’obiettivo REACH deve includere il posizionamento TWITTER_TIMELINE. Può includere ALL_ON_TWITTER, qualsiasi combinazione di posizionamenti che includa TWITTER_TIMELINE oppure TWITTER_TIMELINE da solo.

​

Domande frequenti sui gruppi pubblicitari

Questo documento raccoglie le domande più comuni sui gruppi pubblicitari nella X Ads API.

​

Che cos’è un gruppo pubblicitario?

I gruppi pubblicitari, chiamati line item nella X Ads API, sono contenuti all’interno delle campagne e vengono utilizzati per il targeting e le offerte su un insieme di utenti di X. Gli inserzionisti promuovono Tweet o contenuti multimediali (ad esempio, video promossi come annunci In-stream) associandoli a un line item.

​

Come creiamo un gruppo pubblicitario?

I gruppi pubblicitari si creano chiamando più volte POST accounts/:account_id/line_items per lo stesso ID campagna e mantenendo il targeting (anche completamente diverso) e i Tweet associati a tali line item. C’è un limite di 100 line item per campagna e un limite di 200 campagne attive per un singolo account pubblicitario. Complessivamente, c’è un limite di 8.000 line item attivi per account pubblicitario.

​

Perché dovremmo aggiungere il supporto per i Gruppi di annunci?

I Gruppi di annunci sono pensati per semplificare agli inserzionisti l’organizzazione, l’ottimizzazione e la gestione delle campagne.

Il vantaggio dei Gruppi di annunci è poter confrontare e controllare diverse strategie in termini di offerta, budget, creatività e targeting. Quando si associano più Tweet promossi a un singolo line item, l’asta seleziona il Tweet migliore da quel gruppo e poi seleziona il Tweet migliore per quella campagna tra tutti i line item. Se disponi di più Gruppi di annunci con singoli Tweet, selezionerà di fatto il Tweet che con maggiore probabilità darà le migliori prestazioni da quel Gruppo di annunci.

L’uso dei Gruppi di annunci consente a un inserzionista di suddividere targeting e offerta in un numero molto più ampio di combinazioni possibili e, in generale, permette di segmentare il targeting in gruppi logici.

Gli strumenti della X Ads API, in particolare, potrebbero essere costruiti attorno a regole di ottimizzazione finemente tarate con i Gruppi di annunci, cosa che sarebbe più difficile ottenere tramite modifiche manuali a causa dell’ampia scala di combinazioni tra line item e creatività.

​

In che modo il budget della line item è correlato al budget della campagna in una campagna Ad Groups?

Il valore di total_budget_amount_local_micro per una line item non può superare il budget totale della campagna principale. Analogamente, il valore di bid_amount_local_micro della line item non dovrebbe superare daily_budget_amount_local_micro o total_budget_amount_local_micro della campagna principale. Un’impostazione errata di questi valori può mettere l’intera campagna in stato di pausa e non erogabile.

Si noti che il budget totale della campagna può essere inferiore alla somma dei budget delle sue line item figlie e che la distribuzione del budget tra le line item è in parte lasciata allo strumento X Ads API, che può ottimizzarla e modificarla in modo efficace, poiché le prestazioni giornaliere del targeting (line item) possono variare sensibilmente di giorno in giorno a causa della natura in tempo reale di X.

​

Gli Ad Group offrono prestazioni migliori rispetto a singoli line item?

Le prestazioni di una campagna dipendono da molti fattori e, in definitiva, è il Tweet a determinare il risultato finale. Un line item incide sul fatto che un Tweet sia o meno idoneo a essere mostrato a un utente.

I line item che puntano agli stessi gruppi di utenti presentano una sovrapposizione di audience. È considerata una best practice ridurre questa sovrapposizione di targeting tra i line item, così da identificare chiaramente i gruppi di utenti con le prestazioni migliori.

​

Guide

​

Obiettivo Visualizzazioni video (Preroll)

La seguente guida descrive i passaggi necessari per configurare una campagna PREROLL_VIEWS sulla X Ads API. In termini generali, queste campagne sono suddivise in due tipologie: Curated Categories e Content Categories (indicate come Standard Categories nell’interfaccia Ads).  

​

Endpoint necessari

• Chunked media upload (per il caricamento dei video)
• POST accounts/:account_id/media_library (per associare il video all’account pubblicitario)
• POST accounts/:account_id/campaigns (creare una campagna)
• GET content_categories (per ottenere la corrispondenza tra categorie di contenuto e categorie IAB)
• GET accounts/:account_id/curated_categories
• GET publishers
• POST accounts/:account_id/line_item_curated_categories
• POST accounts/:account_id/line_items (creare un gruppo di annunci)
• POST accounts/:account_id/media_creatives (per associare il video al gruppo di annunci)
• POST accounts/:account_id/preroll_call_to_action (impostare la CTA e l’URL di reindirizzamento)
• POST batch/accounts/:account_id/targeting_criteria (targeting)

​

Procedura

​

Caricare il video

Il caricamento del video prevede 2 passaggi:

​

Carica il contenuto multimediale video

Per prima cosa, utilizzando l’endpoint Chunked media upload, caricherai il video su X per l’elaborazione. Devi passare media_category=amplify_video nella chiamata INIT iniziale usando questo endpoint. Caricherai il video in segmenti. Una volta che STATUS restituisce uno state pari a succeeded, puoi procedere con i passaggi successivi. Ulteriori informazioni sul caricamento dei media tramite l’endpoint chunked sono disponibili nella nostra Panoramica di Promoted Video.

​

Aggiungere il video all’account pubblicitario

Quando lo stato restituito dal comando STATUS è succeeded, usa il media_key restituito da tale endpoint per aggiungere il video alla libreria multimediale dell’inserzionista tramite 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
 }
}

​

Configura la campagna

​

Creazione della campagna

Crea la campagna e il line item/gruppo di annunci. I line item devono essere creati con objective impostato su VIDEO_VIEWS_PREROLL e product_type impostato su MEDIA. Il parametro categories deve inoltre essere impostato sulle categorie di attività dell’inserzionista appropriate.

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

​

Creazione dei line item

I line item devono avere il parametro categories impostato sul set appropriato di categorie IAB, recuperate tramite l’endpoint GET content_categories. Ciascuna di queste categorie di contenuto corrisponde a una o più categorie IAB.

Per utilizzare questi valori, i partner devono selezionare una categoria di contenuto appropriata e utilizzare l’intero set di iab_categories restituito nella risposta per impostare il parametro categories sull’endpoint dei line item. Qualsiasi applicazione parziale di iab_categories comporterà l’impostazione dell’intero gruppo sul line item. Ad esempio,

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

{
  "request": {
    "params": {}
  },
  "next_cursor": null,
  "data": \[
    {
      "id": "1jl",
      "name": "Beni di largo consumo confezionati",
      "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": "Sanità e farmaceutica",
      "iab_categories": \[
        "IAB7"
      \]
    },
    {
      "id": "1jn",
      "name": "Alcolici",
      "iab_categories": \[
        "IAB8-5",
        "IAB8-18"
      \]
    },
    {
      "id": "1jo",
      "name": "Ristorazione",
      "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": "Servizi finanziari",
      "iab_categories": \[
        "IAB3",
        "IAB13",
        "IAB21"
      \]
    },
    {
      "id": "1jq",
      "name": "Retail",
      "iab_categories": \[
        "IAB18"
      \]
    },
    {
      "id": "1jr",
      "name": "Viaggi",
      "iab_categories": \[
        "IAB20"
      \]
    },
    {
      "id": "1js",
      "name": "Gaming",
      "iab_categories": \[
        "IAB9-30"
      \]
    },
    {
      "id": "1jt",
      "name": "Tecnologia",
      "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": "Telecomunicazioni",
      "iab_categories": \[
        "IAB19-6",
        "IAB19-18"
      \]
    },
    {
      "id": "1jv",
      "name": "Automotive",
      "iab_categories": \[
        "IAB2"
      \]
    },
    {
      "id": "1jw",
      "name": "Media e intrattenimento",
      "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": "Politica",
      "iab_categories": \[
        "IAB11-4"
      \]
    },
    {
      "id": "1jy",
      "name": "Giochi d’azzardo",
      "iab_categories": \[
        "IAB9-7"
      \]
    },
    {
      "id": "1jz",
      "name": "Incontri",
      "iab_categories": \[
        "IAB14-1"
      \]
    },
    {
      "id": "1k0",
      "name": "No profit",
      "iab_categories": \[
        "IAB11-1",
        "IAB11-2",
        "IAB11-3",
        "IAB11-5"
      \]
    }
  \]
}

Ora, per impostare il parametro categories su “Science & Education”, è necessario impostare per la line item l’intero set di iab_categories, cioè "IAB5", "IAB15", come segue:

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

​

Selezione del publisher

Un inserzionista può scegliere di indirizzare una Content Category oppure una Curated Category; ulteriori dettagli sono riportati di seguito.

Nota: Le line item possono indirizzare categorie Curated o Content, ma non entrambe. 

​

Categorie curate

Le Categorie curate consentono agli inserzionisti di targettizzare un gruppo predefinito di publisher e possono essere recuperate tramite l’endpoint GET curated_categories. Queste categorie sono specifiche per paese e pertanto richiedono che il line item targettizzi il paese appropriato in base al country_code della categoria.

Per utilizzare una di queste categorie, attenersi ai seguenti passaggi nell’ordine indicato:

1. Il line item deve targettizzare il paese appropriato in base al country_code della Categoria curata
2. È necessario utilizzare l’endpoint POST line_item_curated_categories per associare il line item a uno specifico curated_category_id.

Nota: L’associazione di un line item a una categoria curata limiterà anche il numero di publisher che possono essere inseriti in denylist a 5. L’elenco completo degli user_id utilizzati per mettere in denylist specifici publisher può essere recuperato dall’endpoint GET publishers. Inoltre, un dato line item può targettizzare non più di una Categoria curata alla volta.

Il seguente esempio illustra come associare un id di categoria curata: b0xt, disponibile solo negli Stati Uniti, con il line item creato nel passaggio precedente.

Per prima cosa, i criteri di targeting del line item vengono impostati sul valore 96683cc9126741d

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

{
  "data": \[
    {
      "name": "Stati Uniti",
      "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": "Stati Uniti"
      "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
  }
}

​

Categorie di contenuto

Le categorie di contenuto, dette anche Categorie standard, possono essere recuperate dall’endpoint GET curated_categories. Queste categorie possono poi essere selezionate per il line item utilizzando gli endpoint per i criteri di targeting in batch. Il seguente esempio illustra come selezionare una specifica categoria di contenuto, id: sr, che corrisponde a “News & Current Events”, e applicarla al line item.

Nota: L’intero set di iab_categories nella risposta di GET curated_categories deve essere preso di mira tramite l’endpoint dei criteri di targeting. In caso contrario si verificherà un errore di convalida. 

GET https://ads-api.x.com/8/content_categories
{
      "name": "Notizie e attualità",
      "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": "Notizie",
      "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": "Società"
      "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"
    }
  \]
}

Associare i media dell’account (video) alla line item

Usare l’endpoint POST accounts/:account_id/media_creatives per associare il video a un gruppo di annunci.

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":"APPROVATO",
   "created_at":"2016-02-11T22:23:23Z",
   "deleted":false,
   "id":"qeq",
   "landing_url":null,
   "line\_item\_id":"4bii5",
   "serving_status":"ATTIVO"
   "updated_at":"2016-02-11T22:23:23Z"
 },
 "request":{
   "params":{
     "line\_item\_id":"4bii5",
     "account\_media\_id":"knb"
   }
 }
}

​

Imposta la CTA e l’URL di destinazione

È importante notare che, a differenza della maggior parte delle altre campagne su X, l’obiettivo VIDEO_VIEWS_PREROLL non utilizza Promoted Tweets o Cards. In questo caso, la creatività video è associata al tuo gruppo di annunci (line item) e le informazioni sulla CTA sono associate a un’entità preroll_call_to_action. L’endpoint POST accounts/:account_id/preroll_call_to_action consente di controllare il pulsante della CTA e l’URL di destinazione.

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

​

Impostare i criteri di targeting

Il criterio di targeting utilizzato per gli annunci video pre-roll è disponibile esclusivamente tramite il nostro endpoint batch dei criteri di targeting POST batch/accounts/:account_id/targeting_criteria.

Usa CONTENT_PUBLISHER_USER come targeting negato per evitare che l’annuncio venga associato a un insieme di utenti. Fornisci lo user_id di X o il publisher_user_id per gli handle da escludere.

L’endpoint GET publishers può essere utilizzato per recuperare l’elenco degli user_id da escludere per le Content Categories. Il publisher_user_id restituito nella risposta di GET curated_categories può essere utilizzato per ottenere un elenco di esclusioni analogo per le Curated Categories.

Nota: È possibile escludere al massimo 5 publisher_user_id per le Curated Categories e 50 user_id per le 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"
    }
  \]
}

​

Avvia la campagna

Quando sei pronto ad avviare la campagna, ti basta riattivarla utilizzando 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

Le analytics per le campagne VIDEO_VIEWS_PREROLL sono disponibili tramite i nostri endpoint delle statistiche.

​

Targeting per parola chiave nei timeline

Il targeting per parola chiave è fondamentale per i nostri prodotti Promoted Tweets, migliorando la portata delle campagne. Il targeting per parola chiave nel timeline consente alle piattaforme di raggiungere gli utenti di X in base alle parole chiave presenti nei loro Tweet recenti. Ad esempio, se un inserzionista sta usando come target la combinazione non ordinata di parole chiave “plan + trip” e un utente pubblica un Tweet: “I’m starting to plan my trip to Cabo, any suggestions?” mentre la campagna è attiva, quell’utente potrebbe poco dopo vedere il Promoted Tweet dell’inserzionista.

​

Come funziona?

In breve: dal punto di vista dell’API, questa modifica è piuttosto semplice: ora puoi targettizzare parole chiave sui Promoted Tweets nel feed. Imposta targeting_type su unordered_keywords o phrase_keywords per le line item.

​

Guida di avvio rapido

• Crea una nuova line item con il posizionamento impostato su ALL_ON_TWITTER o TWITTER_TIMELINE POST accounts/:account_id/line_items
• Crea i criteri di targeting per questa nuova line item utilizzando BROAD_KEYWORD e imposta i valori della/e parola/e chiave. POST accounts/:account_id/targeting_criteria
• Puoi aggiornare le parole chiave con PUT accounts/:account_id/targeting_criteria
• Una volta che la campagna è in esecuzione, recupera le statistiche sulla line item per valutarne le prestazioni. GET stats/accounts/:account_id

​

Riferimento all’API

​

Account

Apri in Postman

​

GET accounts

Recupera i dettagli di alcuni o tutti gli account abilitati alla pubblicità a cui l’utente autenticato ha accesso.

URL della risorsa

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

Parametri

Nome	Descrizione
account_ids opzionale	Limita la risposta ai soli ID degli account desiderati specificando un elenco di identificatori separati da virgole. Type: string Example: 18ce54d4x5t
count opzionale	Specifica il numero di record da recuperare per ciascuna richiesta. Type: int Default: 200 Min, Max: 1, 1000
cursor opzionale	Specifica un cursore per ottenere la pagina successiva dei risultati. Vedi Paginazione per ulteriori informazioni. Type: string Example: 8x7v00oow
q opzionale	Query opzionale per filtrare la risorsa per name. Nota: Esegue una corrispondenza per prefisso senza distinzione tra maiuscole e minuscole. Type: string Lunghezza min, max: 1, 255
sort_by opzionale	Ordina per un attributo supportato, in ordine crescente o decrescente. Vedi Ordinamento per ulteriori informazioni. Type: string Example: created_at-asc
with_deleted opzionale	Includi i risultati eliminati nella richiesta. Type: boolean Default: false Valori possibili: true, false
with_total_count opzionale	Includi l’attributo di risposta total_count. Nota: Questo parametro e cursor sono mutuamente esclusivi. Nota: Le richieste che includono total_count avranno limiti di velocità inferiori, attualmente impostati a 200 ogni 15 minuti. Type: boolean Default: false Valori possibili: true, false

​

Esempio di richiesta

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

Esempio di risposta

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

Recupera un account specifico a cui l’utente autenticato ha accesso.

Resource URL

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

Parameters

Name	Description
account_id required	L’identificatore dell’account utilizzato. Compare nel path della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’Advertiser API, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
with_deleted optional	Includi nella richiesta anche i risultati eliminati. Type: boolean Default: false Possible values: true, false

Example Request

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

Example Response

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

Nota: SOLO SANDBOX

Crea un account pubblicitario nell’ambiente sandbox.

URL della risorsa

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

Parametri

Nessuno

Esempio di richiesta

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

Esempio di risposta

       {
         "request": {
           "params": {}
         },
         "next_cursor": null,
         "data": [
           {
             "name": "Account sandbox",
             "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": "APPROVATO"
             "deleted": false
           }
         ]
       }

​

PUT accounts/:account_id

Aggiorna il nome dell’account e/o il settore.

Resource URL

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

Parameters

Nome	Descrizione
account_id required	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro richiesto per tutte le richieste dell’API Advertiser, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
name optional	Il nome dell’account. Type: string Example: API McTestface
industry_type optional	Il settore a cui è associato l’account. Type: string Possible values: AGENCY, BUSINESS_TO_BUSINESS, ONLINE_SERVICES, EDUCATION, FINANCIAL, HEALTH, GOVERNMENT, MEDIA, MOBILE, RESTAURANT, RETAIL, TECHNOLOGY, TRAVEL, OTHER

Example Request

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

Example Response

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

Nota: SOLO SANDBOX

Elimina un account pubblicitario nell’ambiente sandbox.

Resource URL

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

Parameters

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API Advertiser, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Esempio: 18ce54d4x5t

Example Request

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

Example Response

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

​

App dell’account

Apri in Postman ❯

​

GET account_apps

Recupera i dettagli di tutte le app mobile associate all’account pubblicitario specificato.

Resource URL

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

Parameters

Name	Description
account_id required	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API Advertiser, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
count optional	Specifica il numero di record da recuperare per ciascuna richiesta. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Specifica un cursore per ottenere la pagina successiva dei risultati. Vedi Pagination per maggiori informazioni. Type: string Example: 8x7v00oow
sort_by optional	Ordina in base a un attributo supportato, in ordine crescente o decrescente. Vedi Sorting per maggiori informazioni. Type: string Example: created_at-asc
with_deleted optional	Includi i risultati eliminati nella richiesta. Type: boolean Default: false Possible values: true, false
with_total_count optional	Includi l’attributo di risposta total_count. Nota: Questo parametro e cursor sono mutuamente esclusivi. Nota: Le richieste che includono total_count avranno limiti di velocità più bassi, attualmente pari a 200 ogni 15 minuti. Type: boolean Default: false Possible values: 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
          }
         ]
       }

​

Cronologia account

Apri in Postman

​

GET accounts/:account_id/account_history

Recupera un riepilogo delle modifiche apportate all’entity_id specificato nella richiesta.

Nota: Questo endpoint è attualmente in beta e richiede l’inserimento in allowlist.

Resource URL

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

Parameters

Name	Description
account_id required	L’identificatore dell’account utilizzato. Type: string Example: 18ce54d4x5t
count optional	Specifica il numero di record da tentare di recuperare per ogni singola richiesta. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Specifica un cursore per ottenere la pagina successiva di risultati. Vedere Pagination per ulteriori informazioni. Type: string Example: 8x7v00oow
entity_type required	Il tipo di entità per cui recuperare i dati. Type: enum Example: PROMOTED_TWEET Possible values: CAMPAIGN, LINE_ITEM, PROMOTED_TWEET, TARGETING_CRITERIA, PROMOTED_ACCOUNT
entity_id required	L’entità specifica per cui recuperare i dati. Type: string Example: 8u94t
start_time required	Limita i dati recuperati all’ora di inizio specificata, espressa in ISO 8601. Nota: Deve essere espressa in ore intere (0 minuti e 0 secondi). Type: string Example: 2017-05-19T07:00:00Z
end_time required	Limita i dati recuperati all’ora di fine specificata, espressa in ISO 8601. Nota: Deve essere espressa in ore intere (0 minuti e 0 secondi). Type: string Example: 2017-05-26T07:00:00Z
user_id optional	Limita la risposta a un utente specifico. Type: long Example: 3271358660

Example Request

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

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "entity": "CAMPAIGN",
          "entity_id": "fc3h5",
          "count": 1
        }
      },
      "next_cursor": "1r2407sb4lc",
      "data": [
        {
          "change_by": {
            "user_id": "982978172",
            "platform": "API_OTHER"
          },
          "changes": {},
          "change_time": "2021-04-02T20:55:42Z",
          "entity_id": "fc3h5",
          "entity": "CAMPAIGN",
          "entity_data": {
            "name": "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"
        }
      ]
    }

​

Categorie di attività per inserzionisti

Apri in Postman

​

GET advertiser_business_categories

Richiedi le categories di attività valide dell’inserzionista per i Gruppi di annunci (line_items) al fine di descrivere il brand dell’inserzionista agli editori.

Nota: queste categorie si applicano solo ai line_items con obiettivo PREROLL_VIEWS e sono distinte dalle content_categories utilizzate per i criteri di targeting.

Ogni advertiser_business_categories rappresenta una raccolta di IAB Categories. Quando si crea un Gruppo di annunci con obiettivo PREROLL_VIEWS, è necessario impostare una o due advertiser_business_categories per il Gruppo di annunci. Questo si può fare impostando il valore del parametro di richiesta categories sull’endpoint line item al set delle corrispondenti iab_categories disponibili tramite questo endpoint.

Ulteriori dettagli sono disponibili nella Guida all’obiettivo Video Views Preroll

Resource URL

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

Parameters

Nessun parametro di richiesta

Example Request

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

Example Response

{
      "request": {
        "params": {}
      },
      "next_cursor": null,
      "data": [
        {
          "id": "1jl",
          "name": "Beni di largo consumo",
          "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": "Sanità e farmaceutica",
          "iab_categories": [
            "IAB7"
          ]
        },
        {
          "id": "1jn",
          "name": "Alcolici",
          "iab_categories": [
            "IAB8-5",
            "IAB8-18"
          ]
        },
        {
          "id": "1jo",
          "name": "Ristorazione",
          "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": "Servizi finanziari",
          "iab_categories": [
            "IAB3",
            "IAB13",
            "IAB21"
          ]
        },
        {
          "id": "1jq",
          "name": "Commercio al dettaglio",
          "iab_categories": [
            "IAB18"
          ]
        },
        {
          "id": "1jr",
          "name": "Viaggi",
          "iab_categories": [
            "IAB20"
          ]
        },
        {
          "id": "1js",
          "name": "Gaming",
          "iab_categories": [
            "IAB9-30"
          ]
        },
        {
          "id": "1jt",
          "name": "Tecnologia",
          "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": "Telecomunicazioni",
          "iab_categories": [
            "IAB19-6",
            "IAB19-18"
          ]
        },
        {
          "id": "1jv",
          "name": "Automotive",
          "iab_categories": [
            "IAB2"
          ]
        },
        {
          "id": "1jw",
          "name": "Media e intrattenimento",
          "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": "Politica",
          "iab_categories": [
            "IAB11-4"
          ]
        },
        {
          "id": "1jy",
          "name": "Scommesse",
          "iab_categories": [
            "IAB9-7"
          ]
        },
        {
          "id": "1jz",
          "name": "Incontri",
          "iab_categories": [
            "IAB14-1"
          ]
        },
        {
          "id": "1k0",
          "name": "Non profit"
          "iab_categories": [
            "IAB11-1",
            "IAB11-2",
            "IAB11-3",
            "IAB11-5"
          ]
        }
      ]
    }

​

Stima del pubblico

Apri in Postman

POST accounts/:account_id/audience_estimate

​

Determina la dimensione approssimativa del pubblico delle tue campagne.

Questo endpoint accetta un array di oggetti JSON contenenti i parametri per gli oggetti dei criteri di targeting. Un elenco dei parametri obbligatori e facoltativi dei criteri di targeting è disponibile all’endpoint POST accounts/:account_id/targeting_criteria. Le richieste devono essere HTTP POST con un corpo JSON e un’intestazione Content-Type: application/json.

Nota: È obbligatorio specificare almeno un criterio di targeting primario; puoi consultare l’elenco di tutti i criteri di targeting primari nella nostra pagina sul targeting delle campagne.

Resource URL

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

Parameters

Name	Description
account_id required	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’Advertiser API, escluso GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
targeting_criteria required	Un oggetto JSON contenente tutti i parametri per gli oggetti dei criteri di targeting. Un elenco dei parametri obbligatori e facoltativi dei criteri di targeting è disponibile all’endpoint POST accounts/:account_id/targeting_criteria.
operator_type optional	Specifica la relazione del criterio di targeting. Ad esempio, per impostare il targeting negato, usa operator_type=NE. Type: enum Possible values: EQ, NE Default: EQ

Example Request

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

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

Esempio di risposta

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

​

Accesso utente autenticato

Apri in Postman

​

GET accounts/:account_id/authenticated_user_access

Recupera le autorizzazioni dell’utente attualmente autenticato (access_token) in relazione allo specifico account pubblicitario. Queste autorizzazioni corrispondono a quelle disponibili su ads.x.com.

Possibili valori:

• ACCOUNT_ADMIN: accesso completo per modificare le campagne e visualizzare le statistiche, inclusa la possibilità di aggiungere o rimuovere utenti e modificare le impostazioni
• AD_MANAGER: accesso completo per modificare le campagne e visualizzare le statistiche, ma non può aggiungere o rimuovere utenti né modificare le impostazioni
• CREATIVE_MANAGER: accesso per modificare i contenuti creativi e visualizzare le anteprime, ma nessun accesso per creare o modificare campagne
• CAMPAIGN_ANALYST: accesso per visualizzare campagne e statistiche, ma nessun accesso per creare o modificare campagne
• ANALYST (“Organic Analyst” su ads.x.com): accesso per visualizzare le analisi organiche e gli insight sul pubblico, ma nessun accesso per creare, modificare o visualizzare campagne
• PARTNER_AUDIENCE_MANAGER: accesso solo via API per visualizzare e modificare i pubblici dei data partner, ma nessun accesso a campagne, creatività o altri tipi di pubblico.

Inoltre, l’autorizzazione TWEET_COMPOSER indica che l’utente autenticato può creare Tweet nullcast (o “solo promossi”) per conto dell’inserzionista. Questa funzionalità è disponibile solo per gli utenti con accesso ACCOUNT_ADMIN, AD_MANAGER o CREATIVE_MANAGER.

Resource URL

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

Parameters

Nessuno

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

​

Regole di offerta

Apri in Postman

​

GET bidding_rules

Recupera le regole di offerta per alcune o tutte le valute. La risposta indicherà le offerte CPE (costo per coinvolgimento) minime e massime.

Sebbene queste regole di offerta cambino raramente, si consiglia di far aggiornare i tuoi sistemi da questi endpoint almeno una volta al mese.

Resource URL

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

Parameters

Name	Description
currency optional	Il tipo di valuta in base al quale filtrare i risultati, identificata secondo lo standard ISO-4217. È una stringa di tre lettere, ad esempio “USD” o “EUR”. Ommetti questo parametro per recuperare tutte le regole di offerta. Type: string Example: USD

Example Request

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

Example Response

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

​

Campagne

Apri in Postman

​

GET accounts/:account_id/campaigns

Recupera i dettagli di alcune o tutte le campagne associate all’account corrente.

Resource URL

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

Parameters

Name	Description
account_id required	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API Advertiser, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
campaign_ids optional	Limita la risposta alle sole campagne desiderate specificando un elenco di identificatori separati da virgole. È possibile fornire fino a 200 ID. Type: string Example: 8wku2
count optional	Specifica il numero di record da tentare di recuperare per ciascuna richiesta. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Specifica un cursore per ottenere la pagina successiva di risultati. Vedi Pagination per maggiori informazioni. Type: string Example: 8x7v00oow
funding_instrument_ids optional	Limita la risposta alle sole campagne sotto specifici strumenti di finanziamento, specificando un elenco di identificatori separati da virgole. È possibile fornire fino a 200 ID. Type: string Example: lygyi
q optional	Una query opzionale per limitare la risorsa in base a name. Type: string Min, Max length: 1, 255
sort_by optional	Ordina in base a un attributo supportato in ordine crescente o decrescente. Vedi Sorting per maggiori informazioni. Type: string Example: created_at-asc
with_deleted optional	Includi nella richiesta anche i risultati eliminati. Type: boolean Default: false Possible values: true, false
with_draft optional	Includi nella richiesta anche i risultati delle campagne in bozza. Type: boolean Default: false Possible values: true, false
with_total_count optional	Includi l’attributo di risposta total_count. Nota: Questo parametro e cursor sono mutuamente esclusivi. Nota: Le richieste che includono total_count avranno limiti di velocità inferiori, attualmente pari a 200 per 15 minuti. Type: boolean Default: false Possible values: true, false

Example Request

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

Example Response

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

​

GET accounts/:account_id/campaigns/:campaign_id

Recupera una campagna specifica associata all’account corrente.

Resource URL

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

Parameters

Name	Description
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’Advertiser API, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
campaign_id obbligatorio	Un riferimento alla campagna su cui si sta operando nella richiesta. Type: string Example: 8wku2
with_deleted opzionale	Includi anche i risultati eliminati nella richiesta. Type: boolean Default: false Possible values: true, false

Example Request

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

Example Response

    {
      "request": {
        "params": {
          "campaign_id": "8wku2",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "name": "test",
        "budget_optimization": "CAMPAGNA",
        "reasons_not_servable": [
          "IN PAUSA PER DECISIONE DELL'INSERZIONISTA",
          "INCOMPLETA"
        ],
        "servable": false,
        "purchase_order_number": null,
        "effective_status": "SCONOSCIUTO",
        "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": "IN PAUSA",
        "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

Crea una nuova campagna associata all’account corrente.

Nota: esiste un limite predefinito di 200 campagne attive per account. Non c’è invece alcun limite al numero di campagne inattive. Questo limite può essere aumentato fino a 8.000 campagne attive. Per abilitare il limite più elevato, l’inserzionista deve inoltrare la richiesta al proprio X Account Manager.

Resource URL

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

Parameters

Name	Description
account_id required	L’identificatore dell’account utilizzato. Compare nel path della risorsa ed è generalmente un parametro richiesto per tutte le richieste dell’API Advertiser, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
funding_instrument_id required	L’identificatore dello strumento di finanziamento sotto cui creare la campagna. Type: string Example: lygyi
name required	Il nome della campagna. Lunghezza massima: 255 caratteri. Type: string Example: demo
budget_optimization optional	Seleziona il tipo di ottimizzazione del budget da applicare. Type: enum Default: CAMPAIGN Possible values: CAMPAIGN, LINE_ITEM
daily_budget_amount_local_micro sometimes required	L’importo del budget giornaliero da allocare alla campagna. Verrà utilizzata la valuta associata allo strumento di finanziamento specificato. Per USD, 5,50 $ è rappresentato come 5500000. Nota: deve essere minore o uguale a total_budget_amount_local_micro ed è richiesto per la maggior parte dei tipi di funding instrument. Type: long Example: 5500000
entity_status optional	Lo stato della campagna. Type: enum Default: ACTIVE Possible values: ACTIVE, DRAFT, PAUSED
purchase_order_number optional	Il numero di riferimento della prenotazione. Usa questo campo per facilitare la quadratura delle fatture. Lunghezza massima: 50 caratteri. Type: string Example: D00805843
standard_delivery optional	Abilita l’erogazione standard o accelerata. Vedi Budget Pacing per ulteriori informazioni sul confronto tra erogazione standard e accelerata. Disponibile solo quando budget_optimization è impostato su CAMPAIGN. Type: boolean Default: true Possible values: true, false
total_budget_amount_local_micro optional	L’importo del budget totale da allocare alla campagna. Verrà utilizzata la valuta associata allo strumento di finanziamento specificato. Per USD, 37,50 $ è rappresentato come 37500000. Type: long Example: 37500000

Example Request

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

Example Response

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

Consente la creazione in batch di nuove campaigns con una singola richiesta.

Richieste in batch

• La dimensione massima attuale del batch è 40.
• Tutti i parametri sono inviati nel body della richiesta ed è richiesto un Content-Type di application/json.
• Le richieste in batch hanno esito negativo o positivo insieme come gruppo e tutte le risposte dell’API, sia in caso di errore sia di successo, preservano l’ordine degli elementi della richiesta iniziale.

Risposte in batch

Le risposte dell’API in batch restituiscono una raccolta ordinata di elementi. Per il resto, sono identiche nella struttura ai rispettivi endpoint a elemento singolo.

Errori in batch

• Gli errori a livello di richiesta (ad es. dimensione massima del batch superata) sono mostrati nella risposta all’interno dell’oggetto errors.
• Gli errori a livello di elemento (ad es. parametro obbligatorio della campagna mancante) sono mostrati nella risposta all’interno dell’oggetto operation_errors.

URL della risorsa

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

Parametri

Nome	Descrizione
operation_type obbligatorio	Il tipo di operazione per elemento eseguita. Type: enum Valori possibili: Create, Delete, Update
params obbligatorio	Un oggetto JSON contenente tutti i parametri per gli oggetti campaign. Per un elenco dei parametri obbligatori e facoltativi della campagna, vedi qui.

Esempio di richiesta

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

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

Esempio di risposta

    {
      "data": [
        {
          "name": "campagne in batch",
          "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": "campagne in batch",
            "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

Aggiorna la campagna specificata associata all’account corrente.

URL della risorsa

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

Parametri

Nome	Descrizione
account_id obbligatorio	Identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è in genere un parametro obbligatorio per tutte le richieste dell’API Advertiser, escluse GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
campaign_id obbligatorio	Riferimento alla campagna su cui operi nella richiesta. Type: string Example: 8wku2
budget_optimization facoltativo	Seleziona il tipo di ottimizzazione del budget da applicare. Type: enum Default: CAMPAIGN Possible values: CAMPAIGN, LINE_ITEM
daily_budget_amount_local_micro facoltativo	Importo del budget giornaliero da allocare alla campagna. Verrà utilizzata la valuta associata allo strumento di finanziamento specificato. Per USD, 5,50 $ è rappresentato come 5500000. Se non fornito, la campagna spenderà in modo uniforme in base al budget totale e alla durata del periodo di erogazione della campagna. Nota: deve essere minore o uguale a total_budget_amount_local_micro. Type: long Example: 5500000
entity_status facoltativo	Stato della campagna. Type: enum Possible values: ACTIVE, PAUSED
name facoltativo	Nome della campagna. Lunghezza massima: 255 caratteri. Type: string Example: demo
purchase_order_number facoltativo	Numero di riferimento dell’ordine d’acquisto. Usa questo campo per facilitare la riconciliazione delle fatture. Lunghezza massima: 50 caratteri. Type: string Example: D00805843
standard_delivery facoltativo	Abilita l’erogazione standard o accelerata. Consulta Budget Pacing per maggiori informazioni sull’erogazione standard rispetto a quella accelerata. Disponibile solo quando budget_optimization è impostato su CAMPAIGN. Type: boolean Default: true Possible values: true, false
total_budget_amount_local_micro facoltativo	Importo del budget totale da allocare alla campagna. Verrà utilizzata la valuta associata allo strumento di finanziamento specificato. Per USD, 37,50 $ è rappresentato come 37500000. Type: long Example: 140000000

Esempio di richiesta

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

Esempio di risposta

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

Elimina la campagna specificata appartenente all’account corrente.

Nota: L’eliminazione di una campagna è irreversibile e i tentativi successivi di eliminare la risorsa restituiranno HTTP 404.

URL della risorsa

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

Parametri

Name	Description
account_id required	Identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API per gli inserzionisti, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
campaign_id required	Riferimento alla campagna su cui si sta operando nella richiesta. Type: string Example: 8yn7m

Esempio di richiesta

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

Esempio di risposta

    {
      "request": {
        "params": {
          "campaign_id": "8yn7m",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "name": "test",
        "budget_optimization": "CAMPAGNA",
        "reasons_not_servable": [],
        "servable": null,
        "purchase_order_number": null,
        "effective_status": "ATTIVA",
        "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": "IN PAUSA",
        "frequency_cap": null,
        "currency": "USD"
        "created_at": "2022-06-03T21:38:07Z",
        "updated_at": "2022-06-03T21:56:35Z",
        "deleted": true
      }
    }

​

Categorie di contenuto

Apri in Postman

​

GET content_categories

Richiedi le categories di contenuto valide da impostare come targeting_criteria per una line item.

Ogni content_category corrisponde a una o più IAB Categories. È possibile farlo impostando targeting_type su IAB_CATEGORY nell’endpoint batch targeting_critera per includere l’insieme di iab_categories corrispondenti restituito dalla richiesta content_categories. In caso contrario, si verificherà un errore di convalida.

I dettagli dell’editore per ciascuna di queste categorie di contenuto possono essere recuperati utilizzando l’endpoint GET publishers.

Ulteriori dettagli sono disponibili nella Video Views Pre-roll Objective Guide.

Resource URL

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

Parameters

Nessun parametro di richiesta

Example Request

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

Example Response

{
      "request": {
        "params": {}
      },
      "next_cursor": null,
      "data": [
        {
          "name": "Automotive (Auto, camion, corse)",
          "id": "ru",
          "iab_categories": [
            "IAB2"
          ],
          "publishers_in_last_thirty_days": 12,
          "videos_monetized_in_last_thirty_days": 316
        },
        {
          "name": "Commedia",
          "id": "sk",
          "iab_categories": [
            "IAB1-4"
          ],
          "publishers_in_last_thirty_days": 19,
          "videos_monetized_in_last_thirty_days": 174
        },
        {
          "name": "Creator digitali",
          "id": "sl",
          "iab_categories": [
            "IAB25-1"
          ],
          "publishers_in_last_thirty_days": 110,
          "videos_monetized_in_last_thirty_days": 1257
        },
        {
          "name": "Intrattenimento e cultura pop",
          "id": "sm",
          "iab_categories": [
            "IAB1-1",
            "IAB1-2",
            "IAB1-3",
            "IAB1-5"
          ],
          "publishers_in_last_thirty_days": 120,
          "videos_monetized_in_last_thirty_days": 3482
        },
        {
          "name": "Notizie finanziarie e di business",
          "id": "sn",
          "iab_categories": [
            "IAB3",
            "IAB13",
            "IAB21"
          ],
          "publishers_in_last_thirty_days": 29,
          "videos_monetized_in_last_thirty_days": 1461
        },
        {
          "name": "Cibo e bevande",
          "id": "so",
          "iab_categories": [
            "IAB8-8",
            "IAB8-12",
            "IAB8-17",
            "IAB8-2",
            "IAB8-3",
            "IAB8-7",
            "IAB8-11",
            "IAB8-4",
            "IAB8-14",
            "IAB8-10",
            "IAB8-15",
            "IAB8-13",
            "IAB8-9",
            "IAB8-16",
            "IAB8-6",
            "IAB8-1"
          ],
          "publishers_in_last_thirty_days": 24,
          "videos_monetized_in_last_thirty_days": 516
        },
        {
          "name": "Lifestyle (moda, viaggi, benessere)",
          "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": "Musica",
          "id": "sq",
          "iab_categories": [
            "IAB1-6"
          ],
          "publishers_in_last_thirty_days": 31,
          "videos_monetized_in_last_thirty_days": 518
        },
        {
          "name": "Notizie e attualità",
          "id": "sr",
          "iab_categories": [
            "IAB12",
            "IAB14"
          ],
          "publishers_in_last_thirty_days": 125,
          "videos_monetized_in_last_thirty_days": 5507
        },
        {
          "name": "Politica",
          "id": "s4",
          "iab_categories": [
            "IAB11"
          ],
          "publishers_in_last_thirty_days": 19,
          "videos_monetized_in_last_thirty_days": 1402
        },
        {
          "name": "Scienza e istruzione",
          "id": "ss",
          "iab_categories": [
            "IAB5",
            "IAB15"
          ],
          "publishers_in_last_thirty_days": 7,
          "videos_monetized_in_last_thirty_days": 132
        },
        {
          "name": "Sport",
          "id": "se",
          "iab_categories": [
            "IAB17"
          ],
          "publishers_in_last_thirty_days": 403,
          "videos_monetized_in_last_thirty_days": 18281
        },
        {
          "name": "Tecnologia",
          "id": "sg",
          "iab_categories": [
            "IAB19"
          ],
          "publishers_in_last_thirty_days": 13,
          "videos_monetized_in_last_thirty_days": 1089
        },
        {
          "name": "Televisione",
          "id": "sh",
          "iab_categories": [
            "IAB1-7"
          ],
          "publishers_in_last_thirty_days": 58,
          "videos_monetized_in_last_thirty_days": 1307
        },
        {
          "name": "Esports e videogiochi"
          "id": "s0",
          "iab_categories": [
            "IAB9-30"
          ],
          "publishers_in_last_thirty_days": 109,
          "videos_monetized_in_last_thirty_days": 1844
        }
      ],
      "total_count": 15
    }

​

Categorie curate

Apri in Postman

​

GET accounts/:account_id/curated_categories

Recupera l’elenco delle Curated Categories disponibili per i country_codes specificati

Ogni curated_category è disponibile solo in determinati paesi indicati dai country_codes nella risposta.

Ulteriori dettagli sono disponibili nella Guida all’obiettivo Video Views Pre-roll.

Resource URL

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

Parameters

Nome	Descrizione
account_id required	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API Advertiser, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
country_codes required	Limita la risposta ai soli paesi desiderati specificando un elenco, separato da virgole, di codici paese ISO a due lettere. È possibile fornire fino a 200 codici. Type: string Example: US
cursor optional	Specifica un cursore per ottenere la pagina successiva di risultati. Consulta Paginazione per ulteriori informazioni. Type: string Example: 8x7v00oow

Example Request

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

Example Response

{
      "request": {
        "params": {
          "country_codes": [
            "US"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "name": "Pallacanestro",
          "description": "Posiziona gli annunci accanto ai migliori contenuti quotidiani di pallacanestro, inclusi squadre universitarie, squadre professionistiche e i principali account dei media sportivi che condividono video di basket durante e fuori stagione.",
          "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": "Personality del gaming",
          "description": "Posiziona gli annunci accanto ai migliori contenuti quotidiani di gaming, esclusivamente da un elenco di alcuni tra i creator digitali di gaming online più grandi e amati.",
          "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": "Posiziona gli annunci accanto ai migliori contenuti quotidiani di baseball, inclusi squadre universitarie, squadre professionistiche e i principali account dei media sportivi che condividono le principali coperture sul 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": "Team di eSport",
          "description": "Posiziona gli annunci accanto alla programmazione delle migliori squadre di eSport al mondo, coprendo sia gli eventi dal vivo sia altra programmazione complementare durante tutto l’anno.",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "759527448757215232",
            "61933836",
            "477213534",
            "907193396049182720",
            "895382891408089089",
            "862708050116976640",
            "115038550",
            "3182089458",
            "4131266472",
            "1145702070961496065",
            "2262070855",
            "920664872786059264",
            "1035653581683220481",
            "14229141",
            "1101275970995027968",
            "20734751",
            "1452520626",
            "720303639277928448",
            "2853641871",
            "912696400571486208",
            "874362688939413504",
            "286505380",
            "892808605170245632",
            "875087838613733376",
            "238431491",
            "867053221940011014",
            "964529942",
            "1172506293174710272",
            "535756639",
            "2255226817",
            "1100825469853696000",
            "1122713320086220803",
            "1124064709295128581",
            "899858978418642944",
            "864977592532688896",
            "864476897106898944",
            "862770685445361665",
            "257268592"
          ],
          "id": "9ys3jz3ktreo",
          "created_at": "2020-10-01T20:02:35Z",
          "updated_at": "2021-03-09T20:36:20Z",
          "videos_monetized_in_last_thirty_days": 169
        },
        {
          "name": "Football ",
          "description": "Posiziona gli annunci accanto ai migliori contenuti quotidiani di football, inclusi squadre universitarie, squadre professionistiche e i principali account dei media sportivi che condividono video di football durante e fuori stagione.",
          "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": "Cultura e lifestyle (uomini)",
          "description": "Eroga annunci accanto a contenuti di una selezione di handle curati in base ai profili dei follower per aiutarti a raggiungere un pubblico prevalentemente maschile, inclusi alcuni dei principali handle che trattano tecnologia, notizie e lifestyle.",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "17764377",
            "61933836",
            "28370738",
            "3224616765",
            "22819823",
            "18927441",
            "734826612684783616",
            "14372486",
            "7157132",
            "15764136",
            "590316679",
            "7302282",
            "895014043932540928",
            "7517222",
            "3489420013",
            "14063426",
            "72665816",
            "214201922",
            "14980903",
            "22199141",
            "21272440",
            "25319414",
            "119593082",
            "4760694445",
            "765905855195803648",
            "238431491",
            "22178780",
            "241544156",
            "25093616",
            "16877611",
            "22146985",
            "368703433",
            "14342661",
            "415605847",
            "2181233851",
            "890891",
            "15764001",
            "614754689",
            "18479513",
            "23508439",
            "348590880"
          ],
          "id": "8tujj1ep7t34",
          "created_at": "2019-08-15T20:49:47Z",
          "updated_at": "2021-03-09T20:39:00Z",
          "videos_monetized_in_last_thirty_days": 1330
        },
        {
          "name": "Cultura e lifestyle (donne)",
          "description": "Eroga annunci accanto a contenuti di una selezione di handle curati in base ai profili dei follower per aiutarti a raggiungere un pubblico prevalentemente femminile, inclusi alcuni dei principali handle che trattano cultura pop, notizie e lifestyle.",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "23482952",
            "20177423",
            "19074134",
            "15566901",
            "32469566",
            "19784831",
            "16145224",
            "16932962",
            "14934818",
            "29730065",
            "24190981",
            "30278532",
            "15846407",
            "24994219",
            "23993734",
            "40965341",
            "16312576",
            "75094638",
            "549673665",
            "18806753",
            "75306892",
            "1482663290",
            "31181674",
            "971407531972186112",
            "4020532937",
            "25087685",
            "22515362",
            "80943051",
            "19247844",
            "15279429",
            "16824090",
            "20710809",
            "979831113655996416",
            "32432308",
            "19472585",
            "25589776",
            "739963476370673665",
            "20188834",
            "926269727663673349"
          ],
          "id": "8tujl1p3yn0g",
          "created_at": "2019-08-15T20:50:24Z",
          "updated_at": "2021-03-09T20:17:53Z",
          "videos_monetized_in_last_thirty_days": 1365
        },
        {
          "name": "Contenuti leggeri",
          "description": "Eroga annunci accanto a un elenco di handle selezionati per l’elevato volume di contenuti positivi e incoraggianti e per le conversazioni che generano costantemente su 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": "Calcio",
          "description": "Eroga annunci accanto al meglio dei contenuti calcistici quotidiani, incluse squadre universitarie, squadre professionistiche e i principali handle dei media sportivi che offrono una copertura di rilievo.",
          "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

Recupera i dettagli di uno specifico curated_category_id

Ogni curated_category è disponibile solo in determinati Paesi indicati dai country_codes nella risposta.

Resource URL

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

Parameters

Name	Description
account_id required	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API per gli inserzionisti, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
curated_category_id required	Un riferimento alla Curated Category con cui stai operando nella richiesta. Type: string Example: 9ddrgesiap6o

Example Request

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

Example Response

    {
      "request": {
        "params": {
          "id": "9ddrgesiap6o",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "name": "Calcio",
        "description": "Accedi ai migliori contenuti calcistici quotidiani, inclusi squadre universitarie, squadre professionistiche e i principali media sportivi che offrono la copertura più importante sul calcio.",
        "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
      }
    }

​

Funzionalità

Apri in Postman

​

GET accounts/:account_id/features

Recupera l’elenco delle funzionalità concesse e accessibili da questo account pubblicitario. Le funzionalità sono identificate da una chiave descrittiva e sono esposte su questo endpoint solo se introdotte in beta o in un altro tipo di rilascio limitato e disponibili nella X Ads API. Le funzionalità che non soddisfano questi criteri non verranno esposte su questo endpoint.

Nota: Questo endpoint supporta lo sviluppo dell’ecosistema della X Ads API migliorando la visibilità sull’accesso dei clienti ai rilasci beta. Gli sviluppatori dell’API non possono richiedere l’accesso alle funzionalità per conto di un inserzionista. Tali richieste possono essere effettuate solo dall’inserzionista al proprio account manager di X.

Resource URL

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

Parameters

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel path della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’Advertiser API, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
feature_keys opzionale	Parametro opzionale che consente di interrogare una specifica chiave di funzionalità. Le richieste possono includere più chiavi separate da virgola. Nota: Solo le funzionalità accessibili da questo account saranno incluse nella risposta. Type: enum Possible values: REACH_AND_FREQUENCY_ANALYTICS, REACH_FREQUENCY_CAP, WEBSITE_CLICKS_CPM_BILLING

Example Request

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

Example Response

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

​

POST accounts/:account_id/features

SOLO SANDBOX

Aggiunge una feature a un account sandbox.

L’elenco aggiornato delle feature dell’account può essere recuperato tramite l’endpoint GET accounts/:account_id/features.

Resource URL

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

Parameters

Name	Description
account_id required	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro richiesto per tutte le richieste della Advertiser API, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: gq180y
feature_keys required	Un elenco di feature, separato da virgole, da aggiungere all’account. Type: enum Possible values: AGE_TARGETING, ALLOW_SKIPPABLE_VIDEOS_FOR_PREROLL_VIEWS_OBJECTIVE, AWARENESS_OBJECTIVE, BRAND_TPN, CHARGE_FOR_GOOD_CLICK, CONVERSATION_CARD, CONVERSATION_CARD_FOUR_OPTIONS, CONVERSATION_CARD_UNLOCK, CPI_CHARGING, DIRECT_MESSAGE_CARD, DR_TAP, ENGAGER_RETARGETING, EVENT_TARGETING, INSTALLED_APP_CATEGORY_TARGETING, MOBILE_CONVERSION_TRANSACTION_VALUE, OPTIMIZED_ACTION_BIDDING, REACH_AND_FREQUENCY_ANALYTICS, REACH_FREQUENCY_CAP, VALIDATED_AGE_TARGETING, VIDEO_VIEWS_MIDROLL_OBJECTIVE, PREROLL_VIEWS_OBJECTIVE, VIDEO_APP_DOWNLOAD_CARD

Example Request

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

Example Response

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

SOLO SANDBOX

Rimuove una funzionalità da un account sandbox.

L’elenco aggiornato delle funzionalità dell’account può essere ottenuto tramite l’endpoint GET accounts/:account_id/features.

Resource URL

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

Parameters

Nome	Descrizione
account_id required	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro richiesto per tutte le richieste dell’API per inserzionisti, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: gq180y
feature_keys required	Un elenco di funzionalità dell’account, separato da virgole, da rimuovere dall’account. Type: enum Possible values: AGE_TARGETING, ALLOW_SKIPPABLE_VIDEOS_FOR_PREROLL_VIEWS_OBJECTIVE, AWARENESS_OBJECTIVE, BRAND_TPN, CHARGE_FOR_GOOD_CLICK, CONVERSATION_CARD, CONVERSATION_CARD_FOUR_OPTIONS, CONVERSATION_CARD_UNLOCK, CPI_CHARGING, DIRECT_MESSAGE_CARD, DR_TAP, ENGAGER_RETARGETING, EVENT_TARGETING, INSTALLED_APP_CATEGORY_TARGETING, MOBILE_CONVERSION_TRANSACTION_VALUE, OPTIMIZED_ACTION_BIDDING, REACH_AND_FREQUENCY_ANALYTICS, REACH_FREQUENCY_CAP, VALIDATED_AGE_TARGETING, VIDEO_VIEWS_MIDROLL_OBJECTIVE, PREROLL_VIEWS_OBJECTIVE, VIDEO_APP_DOWNLOAD_CARD

Example Request

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

Example Response

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

​

Strumenti di finanziamento

Apri in Postman

​

GET accounts/:account_id/funding_instruments

Recupera i dettagli di alcuni o di tutti gli strumenti di finanziamento associati all’account corrente.

Resource URL

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

Parameters

Name	Description
account_id required	L’identificatore dell’account con leva. Compare nel percorso della risorsa ed è generalmente un parametro richiesto per tutte le richieste dell’API per inserzionisti, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
count optional	Specifica il numero di record da recuperare per ciascuna richiesta. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Specifica un cursore per ottenere la pagina successiva dei risultati. Vedi Pagination per maggiori informazioni. Type: string Example: 8x7v00oow
funding_instrument_ids optional	Limita la risposta ai soli strumenti di finanziamento desiderati specificando un elenco di identificatori separati da virgole. Possono essere forniti fino a 200 ID. Type: string Example: lygyi
sort_by optional	Ordina per un attributo supportato in ordine crescente o decrescente. Vedi Sorting per maggiori informazioni. Type: string Example: created_at-asc
with_deleted optional	Includi i risultati eliminati nella richiesta. Type: boolean Default: false Possible values: true, false
with_total_count optional	Includi l’attributo di risposta total_count. Nota: Questo parametro e cursor sono mutuamente esclusivi. Nota: Le richieste che includono total_count avranno limiti di velocità inferiori, attualmente impostati a 200 ogni 15 minuti. Type: boolean Default: false Possible values: true, false

Example Request

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

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "start_time": "2016-07-22T04:24:04Z",
          "description": "Visa con terminazione 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

Recupera uno specifico strumento di finanziamento associato all’account corrente.

Resource URL

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

Parameters

Name	Description
account_id required	Identificatore dell’account con leva. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API Advertiser, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
funding_instrument_id required	Riferimento allo strumento di finanziamento con cui si sta operando nella richiesta. Type: string Example: lygyi
with_deleted optional	Includere i risultati eliminati nella richiesta. Type: boolean Default: false Possible values: 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 con terminazione 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

SOLO SANDBOX

Crea uno strumento di finanziamento nell’ambiente sandbox.

Non c’è alcun rischio di incorrere in costi usando uno strumento di finanziamento sandbox.

URL della risorsa

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

Parametri

Name	Description
account_id required	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è in genere un parametro obbligatorio per tutte le richieste dell’API Advertiser, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: gq1844
currency required	La valuta, espressa in ISO-4217. Type: string Example: USD
start_time required	La data a partire dalla quale lo strumento di finanziamento diventa attivo e utilizzabile, espressa in ISO 8601. Type: string Example: 2017-05-19T07:00:00Z
type required	Il tipo di strumento di finanziamento da creare. Type: enum Possible values: AGENCY_CREDIT_LINE, CREDIT_CARD, CREDIT_LINE, INSERTION_ORDER, PARTNER_MANAGED
end_time sometimes required	La data a partire dalla quale lo strumento di finanziamento diventa inattivo, espressa in ISO 8601. Type: string Example: 2017-05-26T07:00:00Z
credit_limit_local_micro optional	Il credito totale disponibile per questo strumento di finanziamento. Nota: applicabile solo ad alcuni tipi di strumento di finanziamento. Type: long Example: 37500000
funded_amount_local_micro optional	L’importo totale di budget assegnato a questo strumento di finanziamento. Nota: applicabile solo ad alcuni tipi di strumento di finanziamento. Type: long Example: 37500000

Esempio di richiesta

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

Esempio di risposta

    {
      "data": {
        "start_time": "2017-07-10T00:00:00Z",
        "description": "(nessun metodo di pagamento è stato ancora impostato)",
        "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

SOLO SANDBOX

Elimina uno strumento di finanziamento nell’ambiente sandbox.

URL della risorsa

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

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account con leva. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API Advertiser, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: gq1844
funding_instrument_id obbligatorio	Il riferimento allo strumento di finanziamento oggetto della richiesta. Tipo: string Esempio: hxt82

Esempio di richiesta

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

Esempio di risposta

    {
      "data": {
        "start_time": "2017-08-30T19:23:47Z",
        "description": "(nessun metodo di pagamento è stato ancora impostato)",
        "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"
        }
      }
    }

​

Categorie IAB

Apri in Postman

​

GET iab_categories

Richiede le categories dell’App valide per i gruppi pubblicitari (line_items).

Resource URL

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

Parameters

Name	Description
count optional	Specifica il numero di record da recuperare per ciascuna richiesta. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Specifica un cursore per ottenere la pagina successiva delle categorie. Consulta Pagination per maggiori informazioni. Type: string Example: gc-ddf4a
with_total_count optional	Includi l’attributo di risposta total_count. Nota: Questo parametro e cursor si escludono a vicenda. Nota: Le richieste che includono total_count avranno limiti di velocità inferiori, attualmente pari a 200 ogni 15 minuti. Type: boolean Default: false Possible values: true, false

Example Request

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

Example Response

    {
      "data": [
        {
          "id": "IAB1",
          "parent_id": null,
          "name": "Arte e Intrattenimento"
        },
        {
          "id": "IAB1-1",
          "parent_id": "IAB1",
          "name": "Libri e Letteratura"
        }
      ],
      "next_cursor": "uxa8",
      "request": {
        "params": {
          "count": 2
        }
      }
    }

​

Elementi riga

Apri in Postman

​

GET accounts/:account_id/line_items

Recupera i dettagli di alcuni o tutti i line item associati all’account corrente.

Resource URL

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

Parameters

Name	Description
account_id required	Identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è in genere un parametro obbligatorio per tutte le richieste dell’API Advertiser, esclusa GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
campaign_ids optional	Limita la risposta ai soli line item appartenenti a campagne specifiche, specificando un elenco di identificatori separati da virgole. È possibile fornire fino a 200 ID. Type: string Example: 8gdx6
count optional	Specifica il numero di record da provare a recuperare per ciascuna richiesta. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Specifica un cursore per ottenere la pagina successiva di risultati. Vedere Pagination per ulteriori informazioni. Type: string Example: 8x7v00oow
funding_instrument_ids optional	Limita la risposta ai soli line item appartenenti a specifici strumenti di finanziamento, specificando un elenco di identificatori separati da virgole. È possibile fornire fino a 200 ID. Type: string Example: lygyi
line_item_ids optional	Limita la risposta ai soli line item desiderati, specificando un elenco di identificatori separati da virgole. È possibile fornire fino a 200 ID. Type: string Example: 8v7jo
q optional	Query facoltativa per limitare la risorsa in base a name. Type: string Min, Max length: 1, 255
sort_by optional	Ordina per attributo supportato in ordine crescente o decrescente. Vedere Sorting per ulteriori informazioni. Type: string Example: created_at-asc
with_deleted optional	Includi i risultati eliminati nella richiesta. Type: boolean Default: false Possible values: true, false
with_draft optional	Includi nella richiesta i risultati delle campagne in bozza. Type: boolean Default: false Possible values: true, false
with_total_count optional	Includi l’attributo di risposta total_count. Nota: Questo parametro e cursor si escludono a vicenda. Nota: Le richieste che includono total_count avranno limiti di velocità inferiori, attualmente pari a 200 per 15 minuti. Type: boolean Default: false Possible values: true, false

Example Request

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

Example Response

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

​

GET accounts/:account_id/line_items/:line_item_id

Recupera una specifica riga (line item) associata all’account corrente.

URL della risorsa

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

Parametri

Nome	Descrizione
account_id obbligatorio	Identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è in genere un parametro obbligatorio per tutte le richieste dell’API Advertiser, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
line_item_id obbligatorio	Riferimento alla riga (line item) a cui si fa operazione nella richiesta. Type: string Example: 8v7jo
with_deleted opzionale	Includi i risultati eliminati nella richiesta. Type: boolean Default: false Possible values: true, false

Esempio di richiesta

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

Esempio di risposta

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

Crea una riga di ordine associata alla campagna specificata appartenente all’account corrente.

Tutte le righe di ordine all’interno di una campagna devono avere lo stesso product_type e lo stesso objective.

Quando si utilizza il tipo di prodotto PROMOTED_ACCOUNT, associare un Tweet alla line_item aggiunge posizionamenti nel feed su dispositivi mobili, oltre al posizionamento standard PROMOTED_ACCOUNT.

Impostare android_app_store_identifier o ios_app_store_identifier aggiunge automaticamente i criteri di targeting per la riga di ordine corrispondente all’app mobile promossa; ad esempio, fornire ios_app_store_identifier aggiunge i criteri di targeting PLATFORM per iOS.

Nota: è previsto un limite di 100 righe di ordine per campagna e di 256 righe di ordine attive tra tutte le campagne.

Resource URL

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

Parameters

Nome	Descrizione
account_id obbligatorio	L’identificatore per l’account utilizzato. Appare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste API Advertiser ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: 18ce54d4x5t
campaign_id obbligatorio	L’identificatore per la campagna sotto la quale creare la line item. Tipo: string Esempio: 8slvg
end_time obbligatorio	Il momento, espresso in ISO 8601, in cui la line item smetterà di essere pubblicata. Tipo: string Esempio: 2017-10-05T00:00:00Z
objective obbligatorio	L’obiettivo della campagna per questa line item. Tipo: enum Valori possibili: APP_ENGAGEMENTS, APP_INSTALLS, REACH, FOLLOWERS, ENGAGEMENTS, VIDEO_VIEWS, PREROLL_VIEWS, WEBSITE_CLICKS
placements obbligatorio	Le posizioni di placement per questa line item da visualizzare. Specificare un elenco separato da virgole di valori di placement. Tipo: enum Valori possibili: 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 obbligatorio	Il tipo di prodotto promosso che questa line item conterrà. Tipo: enum Valori possibili: MEDIA, PROMOTED_ACCOUNT, PROMOTED_TWEETS
start_time obbligatorio	Il momento, espresso in ISO 8601, in cui la line item inizierà ad essere pubblicata. Tipo: string Esempio: 2017-07-05T00:00:00Z
advertiser_domain talvolta obbligatorio	Il dominio del sito web per questo inserzionista, senza la specifica del protocollo. Nota: Obbligatorio quando il placement della line item è impostato su PUBLISHER_NETWORK. Tipo: string Esempio: x.com
android_app_store_identifier talvolta obbligatorio	L’identificatore Google Play Store per le applicazioni promosse. Nota: Gli obiettivi APP_INSTALLS e APP_ENGAGEMENTS richiedono l’impostazione di almeno un identificatore app store — android_app_store_identifier o ios_app_store_identifier. Tipo: string Esempio: com.twitter.android
bid_amount_local_micro talvolta obbligatorio	L’importo dell’offerta da associare a questa line item. Verrà utilizzata la valuta associata allo strumento di finanziamento specificato. Per USD, $5.50 è rappresentato come 5500000. Nota: Obbligatorio se bid_strategy è impostato su MAX o TARGET Nota: Sono accettati solo valori maggiori di zero. Tipo: long Esempio: 5500000
categories talvolta obbligatorio	Le categorie IAB rilevanti per questo inserzionista. Vedere GET iab_categories. Nota: Obbligatorio quando il placement della line item è impostato su PUBLISHER_NETWORK. Tipo: string Esempio: IAB3-1
ios_app_store_identifier talvolta obbligatorio	La porzione numerica dell’identificatore Apple App Store per le applicazioni promosse. Nota: Gli obiettivi APP_INSTALLS e APP_ENGAGEMENTS richiedono l’impostazione di almeno un identificatore app store — android_app_store_identifier o ios_app_store_identifier. Tipo: string Esempio: 333903271
primary_web_event_tag talvolta obbligatorio	L’identificatore del tag evento web primario. Consente un tracciamento più accurato degli engagement per la campagna relativa a questa line item. Nota: Obbligatorio quando l’obiettivo della line item è impostato su WEBSITE_CONVERSIONS. Tipo: string Esempio: nvo4z
advertiser_user_id opzionale	L’identificatore utente X per l’handle che promuove un annuncio PREROLL_VIEWS. Solo alcune applicazioni client possono utilizzare questo parametro. Tipo: string Esempio: 312226591
audience_expansion opzionale	Utilizzato per espandere la portata delle campagne targetizzando utenti simili a quelli già targetizzati. Nota: Per impostazione predefinita, non verrà applicata alcuna espansione. Tipo: enum Valori possibili: BROAD, DEFINED, EXPANDED
bid_strategy opzionale	Il meccanismo di offerta. AUTO ottimizza automaticamente le offerte basandosi sul budget giornaliero e sulle date di volo della campagna. MAX imposta l’offerta massima consentita e non è disponibile quando l’obiettivo è impostato su REACH o FOLLOWERS. TARGET tenta di mantenere le medie delle offerte giornaliere entro il 20% del bid_amount_local_micro specificato ed è disponibile quando l’obiettivo è impostato su REACH, FOLLOWERS, O WEBSITE_CLICKS. Nota: Se impostato su AUTO, bid_amount_local_micro verrà ignorato. Nota: Predefinito basato sull’obiettivo. Tipo: enum Valori possibili: AUTO, MAX, TARGET
duration_in_days opzionale	Il periodo di tempo entro il quale viene raggiunto il frequency_cap. Tipo: int Valori possibili: 1, 7, 30
entity_status opzionale	Lo stato della line item. Tipo: enum Predefinito: ACTIVE Valori possibili: ACTIVE, DRAFT, PAUSED
frequency_cap opzionale	Il numero massimo di volte che un annuncio può essere consegnato a un utente. Nota: Supportato solo per gli obiettivi REACH, ENGAGEMENTS, VIDEO_VIEWS, e PREROLL_VIEWS. Tipo: int Esempio: 5
goal opzionale	L’impostazione di ottimizzazione da utilizzare con questa line item. L’opzione APP_PURCHASES è disponibile per APP_INSTALL. Le opzioni APP_CLICKS e APP_INSTALLS sono disponibili sia per gli obiettivi APP_INSTALL che APP_ENGAGEMENTS e potrebbero richiedere l’utilizzo di un partner MACT supportato. L’opzione SITE_VISITS è disponibile solo con l’obiettivo WEBSITE_CLICKS. Nota: Predefinito basato sull’obiettivo. Tipo: enum Valori possibili: APP_CLICKS, APP_INSTALLS, APP_PURCHASES,ENGAGEMENT, FOLLOWERS, LINK_CLICKS, MAX_REACH, PREROLL, PREROLL_STARTS, REACH_WITH_ENGAGEMENT, SITE_VISITS, VIDEO_VIEW, VIEW_3S_100PCT, VIEW_6S, VIEW_15S, WEBSITE_CONVERSIONS
name opzionale	Il nome per la line item. Tipo: string Esempio: demo Lunghezza min, max: 1, 255
pay_by opzionale	L’unità in base alla quale addebitare questo elemento pubblicitario. Questa impostazione può essere modificata solo per elementi pubblicitari che utilizzano l’obiettivo APP_INSTALLS. Nota: Il valore predefinito di pay_by viene impostato automaticamente in base all’obiettivo della campagna e all’unità di offerta dell’elemento pubblicitario. L’obiettivo APP_INSTALLS supporta sia i valori APP_CLICK che IMPRESSION. IMPRESSION è il valore predefinito. L’obiettivo LINK_CLICKS supporta sia i valori LINK_CLICK che IMPRESSION. IMPRESSION è il valore predefinito ma non è supportato quando si imposta TARGET per bid_strategy. L’obiettivo SITE_VISITS supporta i valori IMPRESSION. Tipo: enum Valori possibili: APP_CLICK, IMPRESSION, LINK_CLICK
standard_delivery opzionale	Abilita la distribuzione standard o accelerata. Consulta Budget Pacing per maggiori informazioni sulla distribuzione standard rispetto a quella accelerata. Disponibile solo quando budget_optimization è impostato su LINE_ITEM per la campagna principale Tipo: boolean Predefinito: true Valori possibili: true, false
total_budget_amount_local_micro opzionale	L’importo totale del budget da assegnare all’elemento pubblicitario. Verrà utilizzata la valuta associata allo strumento di finanziamento specificato. Per USD, $37.50 è rappresentato come 37500000. Tipo: long Esempio: 37500000
daily_budget_amount_local_micro talvolta richiesto	L’importo del budget giornaliero da assegnare alla campagna. Verrà utilizzata la valuta associata allo strumento di finanziamento specificato. Per USD, $5.50 è rappresentato come 5500000. Quando non fornito, la campagna spenderà uniformemente in base al budget totale e alla durata del periodo di attivazione della campagna. Disponibile solo quando budget_optimization è impostato su LINE_ITEM per la campagna principale Nota: Questo valore dovrebbe essere minore o uguale a total_budget_amount_local_micro. Tipo: long Esempio: 5500000

Esempio di richiesta

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

Esempio di risposta

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

Consente la creazione in batch di nuovi line items con un’unica richiesta.

Richieste in batch

• L’attuale dimensione massima del batch è 40.
• Tutti i parametri vengono inviati nel corpo della richiesta ed è richiesto un Content-Type pari a application/json.
• Le richieste in batch falliscono o riescono insieme come gruppo e tutte le risposte dell’API, sia in caso di errore sia di successo, mantengono l’ordine degli elementi della richiesta iniziale.

Risposte in batch

Le risposte dell’API in batch restituiscono una raccolta ordinata di elementi. Per il resto, sono identiche nella struttura ai corrispondenti endpoint a elemento singolo.

Errori in batch

• Gli errori a livello di richiesta (es. superamento della dimensione massima del batch) sono riportati nella risposta sotto l’oggetto errors.
• Gli errori a livello di elemento (es. parametro obbligatorio del line item mancante) sono riportati nella risposta sotto l’oggetto operation_errors.

URL della risorsa

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

Parametri

Nome	Descrizione
operation_type obbligatorio	Il tipo di operazione per elemento eseguita. Type: enum Valori possibili: Create, Delete, Update
params obbligatorio	Un oggetto JSON contenente tutti i parametri per gli oggetti line item. Per l’elenco dei parametri obbligatori e facoltativi dei line item, vedere qui.

Esempio di richiesta

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

Esempio di risposta

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

Aggiorna la voce di riga specificata associata all’account corrente.

URL della risorsa

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

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore per l’account utilizzato. Appare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API Advertiser, escluso GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: 18ce54d4x5t
line_item_id obbligatorio	Un riferimento al line item con cui stai operando nella richiesta. Tipo: string Esempio: 8v7jo
advertiser_domain opzionale	Il dominio del sito web per questo inserzionista, senza la specifica del protocollo. Nota: Obbligatorio quando il posizionamento del line item è impostato su PUBLISHER_NETWORK. Tipo: string Esempio: x.com
advertiser_user_id opzionale	L’identificatore utente X per l’handle che promuove un annuncio PREROLL_VIEWS. Solo determinate applicazioni client possono utilizzare questo parametro. Tipo: string Esempio: 312226591
android_app_store_identifier opzionale	L’identificatore Google App Store per l’applicazione promossa. Nota: Gli obiettivi APP_INSTALLS e APP_ENGAGEMENTS richiedono l’impostazione di almeno un identificatore app store — android_app_store_identifier o ios_app_store_identifier. Tipo: string Esempio: com.twitter.android
audience_expansion opzionale	Utilizzato per espandere la portata delle campagne targetizzando utenti simili a quelli già targetizzati. Tipo: enum Valori possibili: BROAD, DEFINED, EXPANDED
bid_amount_local_micro opzionale	L’importo dell’offerta da associare a questo line item. Verrà utilizzata la valuta associata allo strumento di finanziamento specificato. Per USD, $5.50 è rappresentato come 5500000. Nota: Obbligatorio se bid_strategy è impostato su MAX o TARGET Nota: Sono accettati solo valori maggiori di zero. Tipo: long Esempio: 140000
bid_strategy opzionale	Il meccanismo di offerta. AUTO ottimizza automaticamente le offerte basandosi sul budget giornaliero e sulle date di volo della campagna. MAX imposta l’offerta massima consentita e non è disponibile quando l’obiettivo è impostato su REACH o FOLLOWERS. TARGET tenta di mantenere le medie delle offerte giornaliere entro il 20% del bid_amount_local_micro specificato ed è disponibile quando l’obiettivo è impostato su REACH o WEBSITE_CLICKS. Nota: Se impostato su AUTO, bid_amount_local_micro verrà ignorato. Nota: Valore predefinito basato sull’obiettivo. Tipo: enum Valori possibili: AUTO, MAX, TARGET
categories opzionale	Le categorie IAB rilevanti per questo inserzionista. Vedi GET iab_categories. Nota: Obbligatorio quando il posizionamento del line item è impostato su PUBLISHER_NETWORK. Tipo: string Esempio: IAB3-1
duration_in_days opzionale	Il periodo di tempo entro il quale viene raggiunto il frequency_cap. Tipo: int Valori possibili: 1, 7, 30
entity_status opzionale	Lo stato del line item. Tipo: enum Valori possibili: ACTIVE, PAUSED
end_time opzionale	Il momento, espresso in ISO 8601, in cui il line item smetterà di essere servito. Tipo: string Esempio: 2017-10-05T00:00:00Z
frequency_cap opzionale	Il numero massimo di volte che un annuncio può essere consegnato a un utente. Nota: Supportato solo per gli obiettivi REACH, ENGAGEMENTS, VIDEO_VIEWS e PREROLL_VIEWS. Tipo: int Esempio: 5
goal opzionale	L’impostazione di ottimizzazione da utilizzare con questo line item. L’opzione APP_PURCHASES è disponibile per APP_INSTALL. Le opzioni APP_CLICKS e APP_INSTALLS sono disponibili per APP_INSTALL e APP_ENGAGEMENTS e potrebbero richiedere l’utilizzo di un partner MACT supportato. Nota: Valore predefinito basato sull’obiettivo. Tipo: enum Valori possibili: 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 opzionale	La porzione numerica dell’identificatore Apple App Store per le applicazioni promosse. Nota: Gli obiettivi APP_INSTALLS e APP_ENGAGEMENTS richiedono l’impostazione di almeno un identificatore app store — android_app_store_identifier o ios_app_store_identifier. Tipo: string Esempio: 333903271
name opzionale	Il nome per il line item. Tipo: string Esempio: demo
pay_by opzionale	L’unità per cui addebitare questo line item. Questa impostazione può essere modificata solo per i line item che utilizzano l’obiettivo APP_INSTALLS. Nota: Il pay_by predefinito viene impostato automaticamente in base all’obiettivo della campagna e all’unità di offerta del line item. L’obiettivo APP_INSTALLS supporta sia i valori APP_CLICK che IMPRESSION. IMPRESSION è il valore predefinito. L’obiettivo LINK_CLICKS supporta sia i valori LINK_CLICK che IMPRESSION. IMPRESSION è il valore predefinito ma non è supportato quando si imposta TARGET per bid_strategy. L’obiettivo SITE_VISITS supporta i valori IMPRESSION. Tipo: enum Valori possibili: APP_CLICK, IMPRESSION, LINK_CLICK
start_time opzionale	Il momento, espresso in ISO 8601, in cui il line item inizierà a essere servito. Tipo: string Esempio: 2017-07-05T00:00:00Z
total_budget_amount_local_micro opzionale	L’importo totale del budget da allocare al line item. Verrà utilizzata la valuta associata allo strumento di finanziamento specificato. Per USD, $37.50 è rappresentato come 37500000. Tipo: long Esempio: 37500000
daily_budget_amount_local_micro opzionale	L’importo del budget giornaliero da allocare alla campagna. Verrà utilizzata la valuta associata allo strumento di finanziamento specificato. Per USD, $5.50 è rappresentato come 5500000. Quando non fornito, la campagna spenderà uniformemente basandosi sul budget totale e sulla durata del tempo di volo della campagna. Disponibile solo quando budget_optimization è impostato su LINE_ITEM per la campagna padre Nota: Questo valore dovrebbe essere minore o uguale al total_budget_amount_local_micro. Tipo: long Esempio: 5500000

Esempio di richiesta

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

Esempio di risposta

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

Elimina la riga elemento specificata appartenente all’account corrente.

Nota: L’eliminazione di una riga elemento è irreversibile e i tentativi successivi di eliminare la risorsa restituiranno HTTP 404.

Nota: Quando una riga elemento viene eliminata, i suoi promoted_tweets figli vengono restituiti negli endpoint GET accounts/:account_id/promoted_tweets e GET accounts/:account_id/promoted_tweets/:promoted_tweet_id solo se with_deleted=true è specificato nella richiesta. Questi promoted_tweets non vengono effettivamente eliminati ("deleted": false nella risposta). Non eseguiamo eliminazioni a cascata.

Resource URL

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

Parameters

Name	Description
account_id required	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro richiesto per tutte le richieste dell’API Advertiser, escluso GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
line_item_id required	Un riferimento alla riga elemento con cui operi nella richiesta. Type: string Example: 9f2ix

Example Request

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

Example Response

    {
      "data": {
        "bid_strategy": "MAX",
        "advertiser_user_id": "756201191646691328",
        "name": "Senza titolo",
        "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"
        }
      }
    }

​

Categorie curate per le line item

Apri in Postman

Ulteriori dettagli sull’uso sono disponibili nella Guida all’obiettivo Video Views Pre-roll

​

GET accounts/:account_id/line_item_curated_categories

Recupera i dettagli di alcune o tutte le categorie curate delle line item associate all’account corrente.

Resource URL

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

Parameters

Name	Description
account_id required	Identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste della Advertiser API, escluso GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
count optional	Specifica il numero di record da tentare di recuperare per ciascuna richiesta. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Specifica un cursore per ottenere la pagina successiva dei risultati. Vedi Pagination per maggiori informazioni. Type: string Example: 8x7v00oow
sort_by optional	Ordina in base a un attributo supportato, in ordine crescente o decrescente. Vedi Sorting per maggiori informazioni. Type: string Example: created_at-asc
with_deleted optional	Includi i risultati eliminati nella richiesta. Type: boolean Default: false Possible values: true, false
with_total_count optional	Includi l’attributo di risposta total_count. Nota: Questo parametro e cursor sono mutuamente esclusivi. Nota: Le richieste che includono total_count avranno limiti di velocità più bassi, attualmente pari a 200 ogni 15 minuti. Type: boolean Default: false Possible values: true, false

Example Request

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

Example Response

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

​

GET accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id

Recupera i dettagli di una specifica categoria curata della line item associata all’account corrente.

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’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API Advertiser, escluso GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
line_item_curated_category_id required	Un riferimento alla categoria curata della line item con cui operi nella richiesta. Type: string Example: 43853bhii885
with_deleted optional	Includi i risultati eliminati nella richiesta. Type: boolean Default: false Possible values: true, false

Example Request

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

Example Response

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

Associa un oggetto curated category alla line item specificata.

Resource URL

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

Parameters

Name	Description
account_id required	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro richiesto per tutte le richieste dell’API Advertiser, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
curated_category_id required	Un riferimento all’entità curated category con cui si opera nella richiesta. Type: string Example: 10miy
line_item_id required	Un riferimento alla line item con cui si opera nella richiesta. Type: string Example: 8v7jo

Example Request

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

Example Response

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

Aggiorna la categoria curata della voce riga specificata.

URL della risorsa

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

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account in uso. È presente nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste della Advertiser API, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
line_item_curated_category_id obbligatorio	Riferimento alla categoria curata della voce riga con cui operi nella richiesta. Type: string Example: 1bzq3
curated_category_id optional	Riferimento all’entità della categoria curata con cui operi nella richiesta. Type: string Example: 10miy
line_item_id optional	Riferimento alla voce riga con cui operi nella richiesta. Type: string Example: 8v7jo

Esempio di richiesta

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

Esempio di risposta

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

Elimina la categoria curata dell’elemento riga specificato.

URL della risorsa

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

Parametri

Nome	Descrizione
account_id obbligatorio	Identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è in genere un parametro obbligatorio per tutte le richieste dell’Advertiser API, escluso GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
line_item_curated_category_id obbligatorio	Riferimento alla categoria curata dell’elemento riga a cui si fa riferimento nella richiesta. Type: string Example: 1bzq3

Esempio di richiesta

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

Esempio di risposta

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

​

Posizionamenti delle line item

Apri in Postman

​

GET line_items/placements

Recupera le combinazioni valide di placement e product_type.

URL della risorsa

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

Parametri

Nome	Descrizione
product_type opzionale	Limita la risposta ai soli placement validi per il tipo di prodotto specificato. Tipo: enum Valori possibili: MEDIA, PROMOTED_ACCOUNT, PROMOTED_TWEETS

Esempio di richiesta

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

Esempio di risposta

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

​

Creatività multimediali

Apri in Postman

​

GET accounts/:account_id/media_creatives

Recupera i dettagli di alcuni o di tutti i media creatives associati all’account corrente.

Resource URL

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

Parameters

Name	Description
account_id required	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro richiesto per tutte le richieste dell’Advertiser API, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
campaign_id optional	Limita la risposta ai soli media creatives associati alla campagna specificata. Type: string Example: 8gdx6
count optional	Specifica il numero di record da tentare di recuperare per ciascuna richiesta. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Specifica un cursore per ottenere la pagina successiva di risultati. Vedi Pagination per maggiori informazioni. Type: string Example: 8x7v00oow
line_item_ids optional	Limita la risposta ai soli media creatives associati alle line items specificate indicando un elenco di identificatori separati da virgola. È possibile fornire fino a 200 ID. Type: string Example: 8v7jo
media_creative_ids optional	Limita la risposta ai soli media creatives desiderati indicando un elenco di identificatori separati da virgola. È possibile fornire fino a 200 ID. Type: string Example: 1bzq3
sort_by optional	Ordina in base a un attributo supportato in ordine crescente o decrescente. Vedi Sorting per maggiori informazioni. Type: string Example: created_at-asc
with_deleted optional	Includi i risultati eliminati nella richiesta. Type: boolean Default: false Possible values: true, false
with_total_count optional	Includi l’attributo di risposta total_count. Nota: Questo parametro e cursor sono mutuamente esclusivi. Nota: Le richieste che includono total_count avranno limiti di velocità inferiori, attualmente impostati a 200 per 15 minuti. Type: boolean Default: false Possible values: true, false

Example Request

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

Example Response

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

​

GET accounts/:account_id/media_creatives/:media_creative_id

Recupera i dettagli di una specifica media creative associata all’account corrente.

Resource URL

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

Parameters

Name	Description
account_id required	Identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API per Inserzionisti, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
media_creative_id required	Riferimento alla media creative con cui operi nella richiesta. Type: string Example: 43853bhii885
with_deleted optional	Includi i risultati eliminati nella richiesta. Type: boolean Default: false Possible values: 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

Associa un oggetto account media al line item specificato.

Usa questo endpoint per promuovere annunci in-stream (quando il creative_type dell’account media è PREROLL) o annunci con immagine (ad esempio BANNER o INTERSTITIAL) su Twitter Audience Platform.

Nota: per aggiungere asset multimediali alla risorsa Account Media, usa l’endpoint POST accounts/:account_id/media_library.

Resource URL

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

Parameters

Nome	Descrizione
account_id required	Identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro richiesto per tutte le richieste dell’Advertiser API, escluso GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
account_media_id required	Riferimento all’entità account media con cui operi nella richiesta. Type: string Example: 10miy
line_item_id required	Riferimento al line item con cui operi nella richiesta. Type: string Example: 8v7jo
landing_url sometimes required	L’URL del sito web a cui indirizzare l’utente. Va usato solo con immagini TAP (o “display creatives”). Questo valore verrà ignorato se usato con asset preroll. Per associare un URL a un asset preroll, usa l’endpoint POST accounts/:account_id/preroll_call_to_actions. Nota: obbligatorio quando l’obiettivo del line item è impostato su WEBSITE_CLICKS. Type: string Example: https://blog.x.com/

Example Request

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

Example Response

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

​

DELETE accounts/:account_id/media_creatives/:media_creative_id

Elimina l’elemento creativo multimediale specificato appartenente all’account corrente.

Resource URL

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

Parameters

Name	Description
account_id required	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è in genere un parametro obbligatorio per tutte le richieste dell’Advertiser API, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
media_creative_id required	Riferimento all’elemento creativo multimediale con cui l’operazione viene eseguita nella richiesta. Type: string Example: 1bzq3

Example Request

DELETE 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": "2021-04-16T21:02:55Z",
        "approval_status": "ACCEPTED",
        "deleted": true
      }
    }

​

Account promossi

Apri in Postman

​

GET accounts/:account_id/promoted_accounts

Recupera i dettagli di alcuni o di tutti gli account promossi associati a una o più line item nell’account corrente.

Usa GET users/lookup per ottenere i dati dell’utente per gli account identificati da user_id nella risposta.

Verrà restituito un HTTP 400 se nessuna delle line item specificate è configurata per contenere account promossi.

Resource URL

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

Parameters

Name	Description
account_id required	Identificatore dell’account utilizzato. Compare nel path della risorsa ed è generalmente un parametro richiesto per tutte le richieste dell’Advertiser API, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
count optional	Specifica il numero di record da tentare di recuperare per ciascuna richiesta. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Specifica un cursore per ottenere la pagina successiva dei risultati. Consulta Pagination per maggiori informazioni. Type: string Example: 8x7v00oow
line_item_ids optional	Limita la risposta agli account promossi associati alle line item specificate indicando un elenco di identificatori separati da virgole. È possibile fornire fino a 200 ID. Type: string Example: 9bpb2
promoted_account_ids optional	Limita la risposta ai soli account promossi desiderati indicando un elenco di identificatori separati da virgole. È possibile fornire fino a 200 ID. Type: string Example: 19pl2
sort_by optional	Ordina in base a un attributo supportato, in ordine crescente o decrescente. Consulta Sorting per maggiori informazioni. Type: string Example: created_at-asc
with_deleted optional	Includi i risultati eliminati nella richiesta. Type: boolean Default: false Possible values: true, false
with_total_count optional	Includi l’attributo di risposta total_count. Nota: Questo parametro e cursor sono mutuamente esclusivi. Nota: Le richieste che includono total_count avranno limiti di velocità inferiori, attualmente pari a 200 per 15 minuti. Type: boolean Default: false Possible values: true, false

Example Request

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

Example Response

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

​

GET accounts/:account_id/promoted_accounts/:promoted_account_id

Recupera un riferimento specifico a un account associato a un line item all’interno dell’account corrente.

URL della risorsa

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

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API Advertiser, esclusa GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: 18ce54d4x5t
promoted_account_id obbligatorio	Il riferimento all’account promosso con cui stai operando nella richiesta. Tipo: string Esempio: 19pl2
with_deleted opzionale	Includi i risultati eliminati nella richiesta. Tipo: boolean Predefinito: false Valori possibili: true, false

Esempio di richiesta

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

Esempio di risposta

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

Associa un account (user_id) alla specifica voce di riga (line item).

Se la line item specificata non è configurata per essere associata a Promoted Accounts, verrà restituito un errore HTTP 400 INCOMPATIBLE_LINE_ITEM. Se l’utente specificato non è idoneo alla promozione, verrà restituito un errore HTTP 400 e nessun utente verrà promosso. Se l’utente indicato è già promosso, la richiesta verrà ignorata.

Per ulteriori informazioni su Promoted Accounts, consulta la nostra pagina di campaign management.

Nota: non è possibile aggiornare (PUT) le entità di Promoted Accounts.

Resource URL

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

Parameters

Name	Description
account_id required	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro richiesto per tutte le richieste dell’Advertiser API, esclusa GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
line_item_id required	Riferimento alla line item a cui si fa operazione nella richiesta. Type: string Example: 9bpb2
user_id required	Riferimento all’utente a cui si fa operazione nella richiesta. Usa GET users/lookup per recuperare l’ID utente (user ID) a partire da uno screen name. Type: long Example: 756201191646691328

Example Request

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

Example Response

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

​

DELETE accounts/:account_id/promoted_accounts/:promoted_account_id

Disassocia un account dalla specifica line item.

URL della risorsa

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

Parametri

Nome	Descrizione
account_id obbligatorio	Identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API per inserzionisti, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
promoted_account_id obbligatorio	Identificatore dell’istanza di un Promoted Account associata a una line item. Type: string Example: 19pl2

Esempio di richiesta

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

Esempio di risposta

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

​

Tweet sponsorizzati

Apri in Postman

​

GET accounts/:account_id/promoted_tweets

Recupera i riferimenti ai Tweet associati alle line item dell’account corrente.

Usa l’endpoint GET accounts/:account_id/tweets per recuperare gli oggetti Tweet. Usa i valori tweet_id per ciascun oggetto promoted_tweets.

Nota: quando le line item padre vengono eliminate, i promoted_tweets vengono restituiti solo se with_deleted=true è specificato nella richiesta. Questi promoted_tweets non sono tuttavia effettivamente eliminati ("deleted": false nella risposta).

Resource URL

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

Parameters

Nome	Descrizione
account_id obbligatorio	Identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API Advertiser, escluso GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
count opzionale	Specifica il numero di record da recuperare per ciascuna richiesta. Type: int Default: 200 Min, Max: 1, 1000
cursor opzionale	Specifica un cursore per ottenere la pagina successiva dei risultati. Vedi Pagination per maggiori informazioni. Type: string Example: 8x7v00oow
line_item_ids opzionale	Limita la risposta ai soli Tweet associati a specifiche line item specificando un elenco di identificatori separati da virgole. Possono essere forniti fino a 200 ID. Type: string Example: 96uzp
promoted_tweet_ids opzionale	Limita la risposta ai soli Tweet promossi desiderati specificando un elenco di identificatori separati da virgole. Possono essere forniti fino a 200 ID. Type: string Example: 1efwlo
sort_by opzionale	Ordina per attributo supportato in ordine crescente o decrescente. Vedi Sorting per maggiori informazioni. Type: string Example: created_at-asc
with_deleted opzionale	Includi i risultati eliminati nella richiesta. Type: boolean Default: false Possible values: true, false
with_total_count opzionale	Includi l’attributo di risposta total_count. Nota: questo parametro e cursor sono mutuamente esclusivi. Nota: le richieste che includono total_count avranno limiti di velocità inferiori, attualmente impostati a 200 per 15 minuti. Type: boolean Default: false Possible values: true, false

Example Request

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

Example Response

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

​

GET accounts/:account_id/promoted_tweets/:promoted_tweet_id

Recupera un riferimento specifico a un Tweet associato a un line item nell’account corrente.

Nota: Quando i line item padre vengono eliminati, i promoted_tweets vengono restituiti solo se nella richiesta è specificato with_deleted=true. Questi promoted_tweets, però, non sono effettivamente eliminati ("deleted": false nella risposta).

Resource URL

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

Parameters

Nome	Descrizione
account_id obbligatorio	Identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API Advertiser, esclusa GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
promoted_tweet_id obbligatorio	Riferimento al Tweet promosso su cui stai operando nella richiesta. Type: string Example: 1efwlo
with_deleted opzionale	Includi i risultati eliminati nella richiesta. Type: boolean Default: false Possible values: true, false

Example Request

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

Example Response

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

​

POST accounts/:account_id/promoted_tweets

Associa uno o più Tweet alla voce di riga specificata. Non tutti i Tweet sono idonei alla promozione, a seconda dell’obiettivo della campagna. Consulta Objective-based Campaigns per ulteriori informazioni.

Quando si utilizza il product type PROMOTED_ACCOUNT, associare un Tweet al line_item aggiunge posizionamenti nella timeline su mobile oltre al posizionamento standard PROMOTED_ACCOUNT.

Nota: non è possibile aggiornare (PUT) le entità Tweet promosse.

Resource URL

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

Parameters

Name	Description
account_id required	Identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro richiesto per tutte le richieste dell’API Advertiser, escluso GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
line_item_id required	Riferimento alla voce di riga con cui si sta operando nella richiesta. Type: string Example: 8v7jo
tweet_ids required	Elenco di identificatori, separati da virgole, corrispondenti a specifici Tweet. È possibile fornire fino a 50 ID. Type: long Example: 822333526255120384

Example Request

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

Example Response

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

​

DELETE accounts/:account_id/promoted_tweets/:promoted_tweet_id

Disassocia un Tweet dalla voce di riga specificata.

Nota: Un’entità promoted_tweets eliminata verrà mostrata come “In pausa” nell’interfaccia ads.x.com. Analogamente, la “messa in pausa” dall’interfaccia disassocerà il Tweet dalla relativa voce di riga.

Resource URL

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

Parameters

Name	Description
account_id required	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’Advertiser API, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
promoted_tweet_id required	Identificatore dell’istanza di un Promoted Tweet associato a una voce di riga. Proviene dal campo id di un elemento della risposta a GET accounts/:account_id/promoted_tweets, non dal tweet_id del Tweet in questione. Fornito nel percorso della risorsa. Type: string Example: 1gp8a5

Example Request

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

Example Response

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

​

Utenti promozionabili

Apri in Postman

​

GET accounts/:account_id/promotable_users

Recupera i dettagli di alcuni o di tutti gli utenti promuovibili associati all’account corrente.

Il tipo di utente promuovibile può essere FULL oppure RETWEETS_ONLY. Questo parametro determina il tipo di contenuti che l’account è autorizzato a promuovere. Gli inserzionisti devono ottenere il permesso per promuovere i contenuti di un altro utente e contattare Twitter per far aggiungere tale utente al tuo account come utente promuovibile RETWEETS_ONLY.

Se le autorizzazioni sono configurate correttamente, puoi inviare richieste agli endpoint dei prodotti promossi che fanno riferimento direttamente all’ID del Tweet che desideri promuovere. Puoi usare l’endpoint POST accounts/:account_id/promoted-tweets per promuovere Tweet pubblicati e l’endpoint POST accounts/:account_id/scheduled-promoted-tweets per promuovere i Tweet programmati dell’account Twitter Ads di un altro inserzionista.

Non è necessario effettuare un Retweet del Tweet di destinazione. Quando promuovi un Tweet con questo approccio, il tweet_id restituito sarà diverso dall’ID del Tweet fornito. In background, il Tweet viene ritwittato come Tweet nullcast e quindi promosso. Il tweet_id restituito corrisponde a questo nuovo Tweet.

Resource URL

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

Parameters

Name	Description
account_id required	L’identificatore dell’account in uso. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API per inserzionisti, escluso GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
count optional	Specifica il numero di record da recuperare per ogni singola richiesta. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Specifica un cursore per ottenere la pagina successiva di risultati. Vedi Pagination per maggiori informazioni. Type: string Example: 8x7v00oow
promotable_user_ids optional	Limita la risposta ai soli utenti promuovibili desiderati specificando un elenco di identificatori separati da virgola. È possibile fornire fino a 200 ID. Type: string Example: l310s
sort_by optional	Ordina per attributo supportato in ordine crescente o decrescente. Vedi Sorting per maggiori informazioni. Type: string Example: created_at-asc
with_deleted optional	Includi i risultati eliminati nella richiesta. Type: boolean Default: false Possible values: true, false
with_total_count optional	Includi l’attributo di risposta total_count. Nota: Questo parametro e cursor si escludono a vicenda. Nota: Le richieste che includono total_count hanno limiti di velocità più bassi, attualmente impostati a 200 ogni 15 minuti. Type: boolean Default: false Possible values: true, false

Example Request

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

Example Response

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

​

GET accounts/:account_id/promotable_users/:promotable_user_id

Recupera un utente promuovibile specifico associato all’account corrente.

Il tipo di utente promuovibile può essere FULL oppure RETWEETS_ONLY. Questo determina il tipo di contenuti che l’account è autorizzato a promuovere.

Gli inserzionisti devono ottenere l’autorizzazione per promuovere i contenuti di un altro utente. Se le autorizzazioni sono impostate correttamente, puoi effettuare richieste agli endpoint del prodotto pubblicitario che fanno riferimento direttamente all’ID del Tweet che desideri promuovere.

Non è necessario fare Retweet del Tweet di destinazione. Quando promuovi un Tweet con questo approccio, il tweet_id restituito sarà diverso dall’ID del Tweet fornito. In background, il Tweet viene retwittato come Tweet nullcast e quindi promosso. Il tweet_id restituito corrisponde a questo nuovo Tweet.

URL della risorsa

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

Parametri

Nome	Descrizione
account_id obbligatorio	Identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste all’API Advertiser, esclusa GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
promotable_user_id opzionale	Riferimento all’utente promuovibile su cui stai operando nella richiesta. Type: string Example: l310s
with_deleted opzionale	Includi i risultati eliminati nella richiesta. Type: boolean Default: false Possible values: true, false

Esempio di richiesta

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

Esempio di risposta

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

​

Editori

Apri in Postman

​

GET publishers

Recupera un elenco di dettagli dei publisher della categoria di contenuti

Ulteriori informazioni sono disponibili nella Video Views Preroll Objective Guide

URL della risorsa

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

Parametri

Nessun parametro di richiesta

Esempio di richiesta

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

Esempio di risposta

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

​

Consigli

Apri in Postman

​

GET accounts/:account_id/recommendations

Stato: Closed Beta

Recupera le raccomandazioni di campagna associate a questo account pubblicitario. Attualmente è previsto un limite di 1 raccomandazione per strumento di finanziamento.

Resource URL

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

Parameters

Name	Description
account_id required	Identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro richiesto per tutte le richieste dell’Advertiser API, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t

Example Request

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

Example Response

    "request": {
      "params": {
        "account_id": "18ce54d4x5t"
      }
    },
    "total_count": 1,
    "data": [
      {
        "funding_instrument_id": "gpvzb",
        "id": "62ce8zza1q0w",
        "account_id": "18ce54d4x5t",
        "status": "IN SOSPESO",
        "message": "Raccomandazione per i test"
        "created_at": "2016-11-14T23:07:54Z",
        "updated_at": "2016-11-14T23:07:54Z"
      }
    ]

​

GET accounts/:account_id/recommendations/:recommendation_id

Stato: Closed Beta

Recupera una specifica raccomandazione di campagna associata a questo account pubblicitario.

La raccomandazione di campagna contiene un set completo di modifiche suggerite per la struttura della campagna, rappresentata come un albero di oggetti. L’albero di risposta è progettato per funzionare insieme agli endpoint della Batch API, ma può anche essere mappato su singoli endpoint di aggiornamento, se appropriato (Create per POST, Update per PUT, Delete per DELETE).

Resource URL

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

Parameters

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’Advertiser API, esclusa GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
recommendation_id obbligatorio	Riferimento all’ID della raccomandazione a cui si fa operazione nella richiesta Type: string Example: 62ce8zza1q0w

Example Request

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

Example Response

{
    "request": {
      "params": {
        "recommendation_id": "62ce8zza1q0w",
        "account_id": "18ce54d4x5t"
      }
    },
    "data_type": "recommendations",
      "data": {
      "changes": [
        {
          "entity_type": "campaigns",
          "params": {
            "start_time": "2016-11-08T22:00:00Z",
            "daily_budget_amount_local_micro": 2200000,
            "end_time": "2016-11-16T07:59:00Z",
            "total_budget_amount_local_micro": 12000000,
            "id": "64m0d"
          },
          "operation_type": "Aggiorna",
          "dependent_entities": [
            {
              "entity_type": "line_items",
              "params": {
                "name": "Campagna per raccomandazioni",
                "placements": [
                  "TWITTER_TIMELINE"
                ],
                "bid_amount_local_micro": 1430000,
                "id": "6f5kq",
                "include_sentiment": "ALL"
              },
              "operation_type": "Aggiorna",
              "dependent_entities": [
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "id": "a8po6p"
                  },
                  "operation_type": null,
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "risultati delle elezioni",
                    "targeting_value": "risultati delle elezioni",
                    "targeting_type": "PHRASE_KEYWORD"
                  },
                  "operation_type": "Crea",
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "id": "101ftp"
                  },
                  "operation_type": "Elimina",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "Uomo",
                    "targeting_value": 1,
                    "targeting_type": "GENDER"
                  },
                  "operation_type": "Crea",
                  "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": "Crea",
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "id": "101fto"
                  },
                  "operation_type": "Elimina",
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "line_item_id": "6f5kq",
                    "display_properties": [],
                    "paused": false,
                    "approval_status": "ACCEPTED",
                    "tweet_id": "91125952589766656"
                  },
                  "operation_type": "Crea",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "Targeting pubblico partner",
                    "targeting_value": "v2cx",
                    "targeting_type": "NEGATIVE_BEHAVIOR"
                  },
                  "operation_type": "Crea",
                  "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": "Crea",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "id": "a8po6o"
                  },
                  "operation_type": "Elimina",
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "line_item_id": "6f5kq",
                    "display_properties": [],
                    "paused": false,
                    "approval_status": "ACCEPTED",
                    "tweet_id": "991101965843460096"
                  },
                  "operation_type": "Crea",
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "line_item_id": "6f5kq",
                    "display_properties": [],
                    "paused": false,
                    "approval_status": "ACCEPTED",
                    "tweet_id": "991127212156096516"
                  },
                  "operation_type": "Crea",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "dibattito",
                    "targeting_value": "dibattito",
                    "targeting_type": "NEGATIVE_PHRASE_KEYWORD"
                  },
                  "operation_type": "Crea",
                  "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": "IN SOSPESO",
      "message": "Raccomandazione per test"
      "created_at": "2016-11-14T23:07:54Z",
      "updated_at": "2016-11-14T23:07:54Z"
      }
    }

​

Tweet promossi programmati

Apri in Postman

​

GET accounts/:account_id/scheduled_promoted_tweets

Recupera i dettagli di alcuni o di tutti i Tweet promossi programmati associati all’account corrente.

URL della risorsa

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

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro richiesto per tutte le richieste dell’API Advertiser, escluso GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
count opzionale	Specifica il numero di record da recuperare per ciascuna richiesta. Type: int Default: 200 Min, Max: 1, 1000
cursor opzionale	Specifica un cursore per ottenere la pagina successiva dei risultati. Vedi Pagination per ulteriori informazioni. Type: string Example: 8x7v00oow
line_item_ids opzionale	Limita la risposta ai soli Tweet programmati associati a specifiche line item specificando un elenco di identificatori separati da virgole. Possono essere forniti fino a 200 ID. Type: string Example: 8xdpe
scheduled_promoted_tweet_ids opzionale	Limita la risposta ai soli Tweet promossi programmati desiderati specificando un elenco di identificatori separati da virgole. Possono essere forniti fino a 200 ID. Type: string Example: 1xboq
sort_by opzionale	Ordina per un attributo supportato in ordine crescente o decrescente. Vedi Sorting per ulteriori informazioni. Type: string Example: created_at-asc
with_deleted opzionale	Includi i risultati eliminati nella richiesta. Type: boolean Default: false Possible values: true, false
with_total_count opzionale	Includi l’attributo di risposta total_count. Nota: Questo parametro e cursor sono mutuamente esclusivi. Nota: Le richieste che includono total_count avranno limiti di velocità inferiori, attualmente pari a 200 ogni 15 minuti. Type: boolean Default: false Possible values: true, false

Esempio di richiesta

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

Esempio di risposta

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

Recupera un Tweet promosso pianificato specifico associato all’account corrente.

URL della risorsa

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

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API per inserzionisti, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: 18ce54d4x5t
scheduled_promoted_tweet_id obbligatorio	Riferimento al Tweet promosso pianificato con cui operi nella richiesta. Tipo: string Esempio: 1xboq
with_deleted opzionale	Includi i risultati eliminati nella richiesta. Tipo: boolean Predefinito: false Valori possibili: true, false

Esempio di richiesta

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

Esempio di risposta

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

Associa un Tweet pianificato alla specifica line item.

Nota: Non è possibile aggiornare (PUT) le entità dei Tweet promossi pianificati.

Resource URL

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

Parameters

Name	Description
account_id required	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è in genere un parametro richiesto per tutte le richieste dell’API Advertiser, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
line_item_id required	Riferimento alla line item con cui stai operando nella richiesta. Type: string Example: 8xdpe
scheduled_tweet_id required	Riferimento al Tweet pianificato con cui stai operando nella richiesta. Type: long Example: 870358555227860992

Example Request

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

Example Response

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

​

DELETE accounts/:account_id/scheduled_promoted_tweets/:scheduled_promoted_tweet_id

Dissocia un Tweet programmato dalla specifica voce di riga.

Nota: scheduled_promoted_tweets può essere eliminato solo prima dell’orario scheduled_at del Tweet programmato.

Resource URL

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

Parameters

Name	Description
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API Advertiser, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
scheduled_promoted_tweet_id obbligatorio	Un riferimento al Tweet promozionale programmato con cui operi nella richiesta. È l’attributo id di un oggetto di risposta GET accounts/:account_id/scheduled_promoted_tweets. Type: string Example: 1xtfl

Example Request

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

Example Response

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

​

Criteri di targeting

Apri in Postman

​

GET accounts/:account_id/targeting_criteria

Recupera i dettagli di alcuni o di tutti i criteri di targeting associati alle linee (line items) dell’account corrente.

Resource URL

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

Parameters

Nome	Descrizione
account_id required	Identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è in genere un parametro richiesto per tutte le richieste dell’API Advertiser, escluso GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
line_item_ids required	Limita la risposta ai soli criteri di targeting delle linee specificate indicando un elenco di identificatori separati da virgole. È possibile fornire fino a 200 ID. Type: string Example: 8u94t
count optional	Specifica il numero di record da recuperare per ciascuna richiesta. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Specifica un cursore per ottenere la pagina successiva dei risultati. Vedi Pagination per ulteriori informazioni. Type: string Example: 8x7v00oow
lang optional	Un codice lingua ISO-639-1. Se presente, nella risposta verrà restituito anche l’attributo localized_name per gli oggetti per i quali è disponibile un nome localizzato. Type: string Example: fr
sort_by optional	Ordina per un attributo supportato in ordine crescente o decrescente. Vedi Sorting per ulteriori informazioni. Type: string Example: created_at-asc
targeting_criterion_ids optional	Limita la risposta ai soli criteri di targeting desiderati indicando un elenco di identificatori separati da virgole. È possibile fornire fino a 200 ID. Type: string Example: dpl3a6
with_deleted optional	Includi i risultati eliminati nella richiesta. Type: boolean Default: false Possible values: true, false
with_total_count optional	Includi l’attributo di risposta total_count. Nota: Questo parametro e cursor sono mutuamente esclusivi. Nota: Le richieste che includono total_count avranno limiti di velocità inferiori, attualmente pari a 200 ogni 15 minuti. Type: boolean Default: false Possible values: true, false

Example Request

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

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "line_item_ids": [
            "8u94t"
          ]
        }
      },
      "next_cursor": null,
      "data": [
        {
          "line_item_id": "8u94t",
          "name": "Targeting per pubblico personalizzato",
          "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

Recupera un criterio di targeting specifico associato all’account corrente.

Resource URL

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

Parameters

Name	Description
account_id required	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API per inserzionisti, escluso GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
targeting_criterion_id required	Un riferimento al criterio di targeting su cui si opera nella richiesta. Type: string Example: eijd4y
lang optional	Un codice lingua ISO-639-1. Se fornito, nella risposta verrà restituito un attributo aggiuntivo localized_name per gli oggetti per i quali è disponibile un nome localizzato. Type: string Example: fr
with_deleted optional	Includi i risultati eliminati nella richiesta. Type: boolean Default: false Possible values: true, false

Example Request

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

Example Response

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

​

POST accounts/:account_id/targeting_criteria

Consulta la pagina Targeting Options per trovare i targeting_value per tipi di targeting specifici. Ti consigliamo di aggiornare tutti i dati settimanalmente, per assicurarti di lavorare con l’insieme più recente di valori dei tipi di targeting. Modifichiamo di tanto in tanto i valori e i criteri di targeting disponibili; sebbene la maggior parte di questi non cambi spesso, alcuni sì. Non vi è alcuna garanzia che questi valori non cambino.

Usa i tipi di targeting BROAD_KEYWORD, EXACT_KEYWORD, PHRASE_KEYWORD o UNORDERED_KEYWORD con le parole chiave specificate in targeting_value. Escludi parole chiave utilizzando il parametro di richiesta operator_type impostato su NE. Vedi targeting keyword types per una descrizione dettagliata di ciascun tipo.

Nota: È possibile indirizzare un solo intervallo di età per line item.

Nota: Per indirizzare una Custom Audience, tale audience deve essere targetable, cioè targetable deve essere uguale a true.

Nota: Quando si utilizza il tipo di targeting TV_SHOW, deve esserci almeno un criterio di targeting LOCATION sul line item prima di impostare il targeting TV_SHOW e tutti i LOCATION devono essere nella stessa locale del TV_SHOW a cui si sta puntando.

Resource URL

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

Parameters

Name	Description
account_id required	L’identificatore dell’account utilizzato. Appare all’interno del path della risorsa ed è generalmente un parametro richiesto per tutte le richieste dell’API per inserzionisti, escluso GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
line_item_id required	Un riferimento al line item con cui stai operando nella richiesta. Type: string Example: 69ob
operator_type required	Specifica la relazione che il criterio di targeting deve avere. Ad esempio, per escludere parole chiave, usa operator_type=NE. Type: enum Possible values: EQ, NE, GTE, LT
targeting_type required	Il tipo di targeting che verrà applicato a questo line item. Possible non-keyword-based values include: 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 Nota: È possibile indirizzare un solo intervallo AGE per line item. Possible keyword-based values include: BROAD_KEYWORD, EXACT_KEYWORD, PHRASE_KEYWORD, UNORDERED_KEYWORD Possible custom audience values include: CUSTOM_AUDIENCE, CUSTOM_AUDIENCE_EXPANDED Possible installed app store category values: APP_STORE_CATEGORY, APP_STORE_CATEGORY_LOOKALIKE Possible Twitter Audience Platform (TAP) app exclusion: APP_LIST (può essere usato solo con operator_type=NE)
targeting_value required	Specifica quale utente, quale interesse, quale località, quale evento, quale piattaforma, quale versione della piattaforma, quale dispositivo, quale parola chiave o frase, quale genere, quale custom audience, quale categoria dello store delle app o quale esclusione di un elenco di app verrà applicata da questo targeting, a seconda del targeting_type selezionato. Type: string Example: 174958347

Example Request

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

Esempio di risposta

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

Consente la creazione in batch di nuove Targeting Criteria con una singola richiesta.

Batch Requests

• La dimensione massima attuale del batch è 500.
• Tutti i parametri sono inviati nel body della richiesta ed è richiesto un Content-Type pari a application/json.
• Le richieste batch falliscono o riescono insieme come gruppo e tutte le risposte dell’API, sia in caso di errore sia di successo, preservano l’ordine degli elementi della richiesta iniziale.

Batch Responses

Le risposte dell’API batch restituiscono una raccolta ordinata di elementi. Per il resto, sono identiche nella struttura ai corrispondenti endpoint a elemento singolo.

Batch Errors

• Gli errori a livello di richiesta (ad es. superamento della dimensione massima del batch) sono riportati nella risposta sotto l’oggetto errors.
• Gli errori a livello di elemento (ad es. parametro Targeting Criteria obbligatorio mancante) sono riportati nella risposta sotto l’oggetto operation_errors.

Resource URL

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

Parameters

Name	Description
operation_type required	Il tipo di operazione per elemento eseguita. Type: enum Possible values: Create, Delete
params required	Un oggetto JSON contenente tutti i parametri per gli oggetti di targeting criteria. Per un elenco dei parametri obbligatori e facoltativi dei targeting criteria, vedere qui. Inoltre, questo endpoint supporta un parametro operator_type che funziona in combinazione con alcuni valori di targeting_type. I valori possibili per questo parametro sono EQ per “uguale a”, GTE per “maggiore o uguale a”, LT per “minore di” e NE per “diverso da”.

Example Request

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

Esempio di risposta

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

Elimina il criterio di targeting specificato appartenente all’account corrente.

Resource URL

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

Parameters

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account in uso. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’Advertiser API, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: 18ce54d4x5t
targeting_criterion_id obbligatorio	Il riferimento al criterio di targeting su cui operi nella richiesta. Tipo: string Esempio: dpl3a6

Example Request

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

Example Response

    {
      "data": {
        "line_item_id": "8u94t",
        "name": "Targeting del pubblico personalizzato",
        "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"
        }
      }
    }

​

Opzioni di targeting

Apri in Postman

• Categorie dell’App Store
• Conversazione
• Dispositivi
• Eventi
• Interessi
• Lingue
• Località
• Operatori di rete
• Versioni della piattaforma
• Piattaforme
• Mercati TV
• Programmi TV

​

GET targeting_criteria/app_store_categories

Scopri i criteri di targeting disponibili basati sulle categorie degli app store per i Prodotti promossi. Le categorie degli app store sono disponibili solo per l’App Store di iOS e per il Google Play Store.

Il targeting per categoria di app installate consente di raggiungere gli utenti in base alle categorie delle app che hanno installato o per le quali hanno manifestato interesse.

Resource URL

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

Parameters

Name	Description
q optional	Una query facoltativa per circoscrivere un criterio di targeting. Ometti questo parametro per recuperare tutto. Type: string Example: music
os_type optional	Limita i risultati a uno specifico app store. Type: enum Possible values: ANDROID, IOS

Example Request

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

Example Response

    {
      "data": [
        {
          "name": "Giochi: musica",
          "targeting_type": "APP_STORE_CATEGORY",
          "targeting_value": "qouq",
          "os_type": "IOS"
        },
        {
          "name": "Musica",
          "targeting_type": "APP_STORE_CATEGORY",
          "targeting_value": "qov2",
          "os_type": "IOS"
        }
      ],
      "request": {
        "params": {
          "q": "musica"
          "os_type": "IOS"
        }
      }
    }

​

GET targeting_criteria/conversations

Esplora i criteri di targeting basati sulle conversazioni disponibili per i Prodotti promossi.

Resource URL

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

Parameters

Nome	Descrizione
conversation_type opzionale	Query opzionale per limitare i risultati a un determinato tipo di conversazione. Type: enum Valori possibili: 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 opzionale	Specifica il numero di record da recuperare per ciascuna richiesta. Type: int Predefinito: 200 Min, Max: 1, 1000
cursor opzionale	Specifica un cursore per ottenere la pagina successiva dei risultati. Consulta Pagination per ulteriori informazioni. Type: string Esempio: 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

Scopri i criteri di targeting disponibili in base al dispositivo per i Prodotti Promossi. Il targeting per dispositivo è disponibile per i Promoted Tweets.

Resource URL

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

Parameters

Name	Description
count optional	Specifica il numero di record da recuperare per ogni singola richiesta. Type: int Default: 200 Min, Max: 1, 1000
q optional	Una query facoltativa per delimitare i criteri di targeting. Ometti questo parametro per recuperare tutti i risultati. Type: string Example: apple

Example Request

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

Example Response

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

Scopri i criteri di targeting basati su eventi disponibili per i Promoted Products. È possibile indirizzare un solo evento per line item.

Nota: Gli eventi spesso si svolgono in più fusi orari, il che può creare complicazioni quando si considerano gli orari da prospettive tra fusi orari diversi. Per semplificare, tutti i valori start_time ed end_time degli eventi su questo endpoint sono rappresentati in UTC±00:00, indipendentemente da località e fuso orario dell’evento. Occorre tenere presente questa impostazione quando si eseguono query e si interagisce con i valori start_time ed end_time degli eventi. Ad esempio, l’Independence Day negli Stati Uniti è rappresentato come start_time=2017-07-04T00:00:00Z ed end_time=2017-07-05T00:00:00Z in UTC±00:00, evitando così il problema di questa festività presente in più fusi orari all’interno degli Stati Uniti.

Resource URL

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

Parameters

Nome	Descrizione
event_types required	Una query opzionale per limitare la ricerca a determinati tipi di evento. Type: enum Valori possibili: CONFERENCE, HOLIDAY, MUSIC_AND_ENTERTAINMENT, OTHER, POLITICS, RECURRING, SPORTS
count optional	Specifica il numero di record da tentare di recuperare per ciascuna richiesta. Type: int Predefinito: 200 Min, Max: 1, 1000
country_codes optional	Una query opzionale per limitare la ricerca dei criteri di targeting a specifici paesi usando il codice paese ISO a 2 lettere. Se questo parametro non è specificato, vengono restituiti tutti gli eventi. Type: string
cursor optional	Specifica un cursore per ottenere la pagina successiva di risultati. Vedi Paginazione per maggiori informazioni. Type: string Esempio: 8x7v00oow
end_time optional	L’ora, espressa in ISO 8601, in cui la campagna terminerà. Type: string Esempio: 2017-10-05T00:00:00Z
start_time optional	L’ora, espressa in ISO 8601, in cui il line item inizierà a erogare. Nota: Predefinito all’ora corrente. Type: string Esempio: 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": "Capodanno",
          "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

Esplora i criteri di targeting basati sugli interessi disponibili per i Prodotti Promossi. Gli interessi cambiano raramente; tuttavia consigliamo di aggiornare questo elenco almeno una volta alla settimana.

Resource URL

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

Parameters

Name	Description
count optional	Specifica il numero di record da recuperare per ciascuna richiesta. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Specifica un cursore per ottenere la pagina successiva dei risultati. Consulta Pagination per maggiori informazioni. Type: string Example: 8x7v00oow
q optional	Query facoltativa per limitare l’ambito di un criterio di targeting. Ometti questo parametro per recuperare tutti i risultati. Type: string Example: books

Example Request

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

Example Response

    {
      "data": [
        {
          "name": "Libri e letteratura/Biografie e memorie",
          "targeting_type": "INTEREST",
          "targeting_value": "1001"
        }
      ],
      "request": {
        "params": {
          "q": "libri"
          "count": 1
        }
      },
      "next_cursor": "6by4n4"
    }

​

GET targeting_criteria/languages

Consulta le lingue disponibili per il targeting.

Resource URL

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

Parameters

Name	Description
count optional	Specifica il numero di record da recuperare per ciascuna richiesta distinta. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Specifica un cursore per ottenere la pagina successiva dei risultati. Consulta Pagination per ulteriori informazioni. Type: string Example: 8x7v00oow
q optional	Una query facoltativa per delimitare un criterio di targeting. Omessi questo parametro per recuperare tutto. Type: string Example: english

Example Request

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

Example Response

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

​

GET targeting_criteria/locations

Scopri i criteri di targeting basati sulla posizione disponibili per i Prodotti Promossi. Il geotargeting è disponibile per Account Promossi e Tweet Promossi a livello di paese, stato/regione, città e codice postale. Il targeting per codice postale deve essere utilizzato se desideri ottenere le analisi a livello di codice postale.

Nota: Per ottenere specifiche città targetizzabili, come San Francisco o New York, usa l’enum CITIES con il parametro di richiesta location_type.

Per targetizzare le Designated Market Areas (DMA), usa l’enum METROS.

Resource URL

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

Parameters

Name	Description
count optional	Specifica il numero di record da recuperare per ogni singola richiesta. Type: int Default: 200 Min, Max: 1, 1000
country_code optional	Query opzionale per limitare la ricerca dei criteri di targeting a un paese specifico utilizzando il codice paese ISO a 2 lettere. Ometti questo parametro per ottenere risultati per tutti i paesi. Type: string Example: JP
cursor optional	Specifica un cursore per ottenere la pagina successiva dei risultati. Vedi Pagination per maggiori informazioni. Type: string Example: 8x7v00oow
location_type optional	Limita i risultati a uno specifico tipo di località. Un targeting più granulare rispetto a COUNTRIES potrebbe non essere disponibile in tutte le località. Type: enum Possible values: COUNTRIES, REGIONS, METROS, CITIES, POSTAL_CODES
q optional	Query opzionale per limitare la ricerca dei criteri di targeting. Ometti questo parametro per ottenere tutti i risultati. Type: string Example: 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, Stati Uniti",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "3b77caf94bfc81fe",
          "targeting_type": "LOCATION"
        },
        {
          "name": "East Los Angeles, Los Angeles CA, CA, Stati Uniti",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "67571a7baaa5906b",
          "targeting_type": "LOCATION"
        },
        {
          "name": "Lake Los Angeles, Los Angeles CA, CA, Stati Uniti",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "ea9bfbd43c93400f",
          "targeting_type": "LOCATION"
        },
        {
          "name": "Los Gatos, San Francisco–Oakland–San Jose CA, CA, Stati Uniti",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "a2de7c70b82b0ca0",
          "targeting_type": "LOCATION"
        },
        {
          "name": "Los Altos, Monterey–Salinas CA, CA, Stati Uniti",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "6a4364ea6f987c10",
          "targeting_type": "LOCATION"
        },
        {
          "name": "Los Banos, CA, Stati Uniti",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "b1b6fc646de75904",
          "targeting_type": "LOCATION"
        },
        {
          "name": "Los Alamitos, Los Angeles CA, CA, Stati Uniti",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "0799ff0a3c1006e9",
          "targeting_type": "LOCATION"
        },
        {
          "name": "Los Angeles, Stati Uniti",
          "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

Esplora i criteri di targeting basati sugli operatori di rete disponibili per i Prodotti promossi.

Questo endpoint consente di cercare gli operatori di telefonia selezionabili come target, ad esempio AT&T, Verizon, Sprint, T-Mobile, ecc., in più paesi.

Resource URL

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

Parameters

Name	Description
count optional	Specifica il numero di record da tentare di recuperare per ogni singola richiesta. Type: int Default: 200 Min, Max: 1, 1000
country_code optional	Parametro opzionale per limitare la ricerca dei criteri di targeting a un paese specifico utilizzando il codice paese ISO a 2 lettere. Se questo parametro non è specificato, vengono restituite solo le audience dei partner per gli Stati Uniti. Type: string Default: US
cursor optional	Specifica un cursore per ottenere la pagina successiva dei risultati. Consulta Pagination per ulteriori informazioni. Type: string Example: 8x7v00oow
q optional	Parametro opzionale per limitare la ricerca dei criteri di targeting. Ometti questo parametro per recuperare tutti i risultati. Type: string Examples: Airpeak

Example Request

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

Example Response

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

​

GET targeting_criteria/platform_versions

Scopri i criteri di targeting disponibili basati sulla versione del sistema operativo mobile per i Prodotti promossi. Il targeting per versione della piattaforma è disponibile per Account promossi e Tweet promossi. Questo consente di indirizzare il targeting fino alla release di punto di una versione del sistema operativo mobile, come Android 8.0 o iOS 10.0.

URL della risorsa

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

Parametri

Nome	Descrizione
q opzionale	Una query opzionale per circoscrivere una ricerca dei criteri di targeting. Ometti questo parametro per recuperare tutti i risultati. Type: string Esempi: jelly bean

Esempio di richiesta

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

Esempio di risposta

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

Scopri i criteri di targeting basati sulla piattaforma disponibili per i Prodotti promossi.

Resource URL

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

Parameters

Name	Description
count optional	Specifica il numero di record da recuperare per ogni singola richiesta. Type: int Default: 200 Min, Max: 1, 1000
q optional	Parametro query facoltativo per delimitare la ricerca dei criteri di targeting. Ometti questo parametro per recuperare tutti i risultati. Type: string Examples: ios, blackberry
lang optional	Codice lingua ISO-639-1. Se fornito, nella risposta verrà restituito anche l’attributo localized_name. Type: int, string Example: fr

Example Request

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

Example Response

    {
      "data": [
        {
          "name": "iOS",
          "targeting_type": "PLATFORM",
          "targeting_value": "0"
        },
        {
          "name": "Android",
          "targeting_type": "PLATFORM",
          "targeting_value": "1"
        },
        {
          "name": "Smartphone e tablet BlackBerry",
          "targeting_type": "PLATFORM",
          "targeting_value": "2"
        },
        {
          "name": "Web mobile su altri dispositivi",
          "targeting_type": "PLATFORM",
          "targeting_value": "3"
        },
        {
          "name": "Computer desktop e portatili",
          "targeting_type": "PLATFORM",
          "targeting_value": "4"
        }
      ],
      "request": {
        "params": {}
      }
    }

​

GET targeting_criteria/tv_markets

Scopri i mercati TV disponibili in cui è possibile targetizzare i programmi TV. Restituisce i mercati per locale che possono essere utilizzati per effettuare query sull’endpoint GET targeting_criteria/tv_shows.

Resource URL

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

Parameters

Nessuno

Example Request

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

Example Response

    {
      "data": [
        {
          "name": "Francia",
          "country_code": "FR",
          "locale": "fr-FR"
        },
        {
          "name": "Cile",
          "country_code": "CL",
          "locale": "es-CL"
        },
        {
          "name": "Germania",
          "country_code": "DE",
          "locale": "de-DE"
        },
        {
          "name": "Paesi Bassi",
          "country_code": "NL",
          "locale": "nl-NL"
        },
        {
          "name": "Stati Uniti",
          "country_code": "US",
          "locale": "en-US"
        },
        {
          "name": "Venezuela",
          "country_code": "VE",
          "locale": "es-VE"
        },
        {
          "name": "Brasile",
          "country_code": "BR",
          "locale": "pt-BR"
        },
        {
          "name": "Messico",
          "country_code": "MX",
          "locale": "es-MX"
        },
        {
          "name": "Colombia",
          "country_code": "CO",
          "locale": "es-CO"
        },
        {
          "name": "Regno Unito",
          "country_code": "GB",
          "locale": "en-GB"
        },
        {
          "name": "Argentina",
          "country_code": "AR",
          "locale": "es-AR"
        },
        {
          "name": "Giappone",
          "country_code": "JP",
          "locale": "ja-JP"
        },
        {
          "name": "Canada",
          "country_code": "CA",
          "locale": "en-CA"
        },
        {
          "name": "Spagna",
          "country_code": "ES",
          "locale": "es-ES"
        },
        {
          "name": "Italia",
          "country_code": "IT",
          "locale": "it-IT"
        },
        {
          "name": "Stati Uniti - ispanici",
          "country_code": "US",
          "locale": "es-US"
        },
        {
          "name": "Irlanda",
          "country_code": "IE",
          "locale": "en-IE"
        }
      ],
      "request": {
        "params": {}
      }
    }

​

GET targeting_criteria/tv_shows

Scopri i criteri di targeting basati sui programmi TV disponibili per i Prodotti Promossi. Il targeting per programmi TV è disponibile per i Promoted Tweets in determinati mercati. Consulta l’endpoint GET targeting_criteria/tv_markets per i mercati disponibili.

Nota: Qualsiasi pubblico con meno di 1.000 utenti verrà mostrato con un valore estimated_users pari a 1000.

Nota: Le opzioni di targeting per canale TV e genere non sono più supportate.

Resource URL

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

Parameters

Nome	Descrizione
locale required	Parametro obbligatorio che specifica il tv_market_locale per eseguire la query dei programmi TV disponibili. I mercati TV vengono interrogati in base al locale restituito da GET targeting_criteria/tv_markets. Type: string Example: en-US
count optional	Specifica il numero di record da recuperare per ciascuna richiesta. Type: int Default: 50 Min, Max: 1, 50
cursor optional	Specifica un cursore per ottenere la pagina successiva dei risultati. Consulta Pagination per maggiori informazioni. Type: string Example: 8x7v00oow
q optional	Query opzionale per delimitare una ricerca dei criteri di targeting. Omessa questo parametro per recuperare tutti i risultati. Type: string Examples: ios, blackberry

Example Request

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

Example Response

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

​

Suggerimenti sul targeting

Apri in Postman

​

GET accounts/:account_id/targeting_suggestions

Ottieni fino a 50 suggerimenti di targeting per parole chiave o utenti per integrare la selezione iniziale.

URL della risorsa

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

Parametri

Nome	Descrizione
account_id obbligatorio	Identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste della Advertiser API, escluso GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
suggestion_type obbligatorio	Specifica il tipo di suggerimenti da restituire. Type: enum Possible values: KEYWORD, USER_ID
targeting_values obbligatorio	Elenco separato da virgole di parole chiave o ID utente utilizzati come seed per generare i suggerimenti. Nota: Questi due tipi di suggerimenti non possono essere combinati. Example: 756201191646691328
count opzionale	Specifica il numero di record da tentare di recuperare per ciascuna richiesta. Type: int Default: 30 Min, Max: 1, 50

Esempio di richiesta

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

Esempio di risposta

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

​

Impostazioni fiscali

Apri in Postman

​

GET accounts/:account_id/tax_settings

Recupera i dettagli delle impostazioni fiscali associate all’account corrente.

URL della risorsa

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

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel path della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API Advertiser, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Esempio: 18ce54d4x5t

Esempio di richiesta

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

Esempio di risposta

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "tax_id": "GB896391250",
        "address_city": "Londra",
        "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": "Londra",
        "address_country": "GB",
        "address_first_name": null,
        "invoice_jurisdiction": "NOT_SET",
        "address_street2": null,
        "address_email": null
      }
    }

​

PUT accounts/:account_id/tax_settings

Aggiorna le impostazioni fiscali dell’account corrente.

URL della risorsa

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

Parametri

Nome	Descrizione
account_id required	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste all’API Ads, escluso GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: 18ce54d4x5t
address_city optional	La città dell’indirizzo del titolare dell’account. Tipo: string Esempio: San Francisco
address_country optional	Il codice paese a due lettere dell’indirizzo del titolare dell’account. Tipo: string Esempio: US
address_email optional	L’email associata all’indirizzo del titolare dell’account. Tipo: string Esempio: [e-mail]
address_first_name optional	Il nome dell’intestatario dell’indirizzo del titolare dell’account. Tipo: string Esempio: API
address_last_name optional	Il cognome dell’intestatario dell’indirizzo del titolare dell’account. Tipo: string Esempio: McTestface
address_name optional	La ragione sociale/denominazione per l’indirizzo del titolare dell’account. Tipo: string Esempio: ABC, Co.
address_postal_code optional	Il codice postale dell’indirizzo del titolare dell’account. Tipo: string Esempio: 94102
address_region optional	La regione dell’indirizzo del titolare dell’account. Tipo: string Esempio: California
address_street1 optional	La prima riga dell’indirizzo stradale del titolare dell’account. Tipo: string Esempio: 21 March St
address_street2 optional	La seconda riga dell’indirizzo stradale del titolare dell’account. Tipo: string Esempio: Suite 99
bill_to optional	L’entità a cui è intestata la fattura. Tipo: enum Valori possibili: ADVERTISER, AGENCY
business_relationship optional	Se l’account è di proprietà dell’inserzionista o dell’agenzia. Tipo: enum Valori possibili: AGENCY, SELF
client_address_city optional	La città dell’indirizzo dell’inserzionista. Impostare questo campo quando l’account pubblicitario è di proprietà di un’agenzia. Tipo: string Esempio: Toronto
client_address_country optional	Il codice paese a due lettere dell’indirizzo dell’inserzionista. Impostare questo campo quando l’account pubblicitario è di proprietà di un’agenzia. Tipo: string Esempio: CA
client_address_email optional	L’email associata all’indirizzo dell’inserzionista. Impostare questo campo quando l’account pubblicitario è di proprietà di un’agenzia. Tipo: string Esempio: [e-mail]
client_address_first_name optional	Il nome dell’intestatario dell’indirizzo dell’inserzionista. Impostare questo campo quando l’account pubblicitario è di proprietà di un’agenzia. Tipo: string Esempio: Brand
client_address_last_name optional	Il cognome dell’intestatario dell’indirizzo dell’inserzionista. Impostare questo campo quando l’account pubblicitario è di proprietà di un’agenzia. Tipo: string Esempio: Advertiser
client_address_name optional	La ragione sociale/denominazione per l’indirizzo dell’inserzionista. Impostare questo campo quando l’account pubblicitario è di proprietà di un’agenzia. Tipo: string Esempio: Brand, Inc.
client_address_postal_code optional	Il codice postale dell’indirizzo dell’inserzionista. Impostare questo campo quando l’account pubblicitario è di proprietà di un’agenzia. Tipo: string Esempio: M5H 2N2
client_address_region optional	La regione dell’indirizzo dell’inserzionista. Impostare questo campo quando l’account pubblicitario è di proprietà di un’agenzia. Tipo: string Esempio: Ontario
client_address_street1 optional	La prima riga dell’indirizzo stradale dell’inserzionista. Impostare questo campo quando l’account pubblicitario è di proprietà di un’agenzia. Tipo: string Esempio: 280 Queen St W
client_address_street2 optional	La seconda riga dell’indirizzo stradale dell’inserzionista. Impostare questo campo quando l’account pubblicitario è di proprietà di un’agenzia. Tipo: string Esempio: The 6
invoice_jurisdiction optional	Giurisdizione di fatturazione. Tipo: enum Valori possibili: LOI_SAPIN, NONE, NOT_SET
tax_category optional	Se la tassazione deve essere individuale o aziendale. Tipo: enum Valori possibili: BUSINESS_NO_VAT, BUSINESS_WITH_VAT, INDIVIDUAL
tax_exemption_id optional	ID di esenzione IVA. Tipo: string Esempio: 12345
tax_id optional	ID di registrazione IVA. Tipo: string Esempio: 67890

Esempio di richiesta

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

Esempio di risposta

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "address_name": "ABC Co."
        }
      },
      "data": {
        "tax_id": "GB896391250",
        "address_city": "Londra",
        "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": "Londra",
        "address_country": "GB",
        "address_first_name": null,
        "invoice_jurisdiction": "NOT_SET",
        "address_street2": null,
        "address_email": null
      }
    }

​

Tag di monitoraggio

Apri in Postman

​

GET accounts/:account_id/tracking_tags

Recupera i dettagli di alcuni o di tutti i tracking tag associati all’account corrente.

Resource URL

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

Parameters

Name	Description
account_id required	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API Advertiser, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
count optional	Specifica il numero di record da recuperare per ciascuna richiesta. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Specifica un cursore per ottenere la pagina successiva di risultati. Vedi Pagination per ulteriori informazioni. Type: string Example: 8x7v00oow
line_item_ids optional	Limita la risposta ai soli tracking tag associati a specifiche line item, specificando un elenco di identificatori separati da virgole. Possono essere forniti fino a 200 ID. Type: string Example: 96uzp
sort_by optional	Ordina in base a un attributo supportato, in ordine crescente o decrescente. Vedi Sorting per ulteriori informazioni. Type: string Example: created_at-asc
tracking_tag_ids optional	Limita la risposta ai soli tracking tag desiderati, specificando un elenco di identificatori separati da virgole. Possono essere forniti fino a 200 ID. Type: string Example: 3m82
with_deleted optional	Includi i risultati eliminati nella richiesta. Type: boolean Default: false Possible values: true, false
with_total_count optional	Includi l’attributo di risposta total_count. Nota: Questo parametro e cursor sono mutuamente esclusivi. Nota: Le richieste che includono total_count avranno limiti di velocità inferiori, attualmente pari a 200 per 15 minuti. Type: boolean Default: false Possible values: 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

Recupera un tag di tracciamento specifico associato all’account corrente.

URL della risorsa

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

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Appare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API Advertiser, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: 18ce54d4x5t
tracking_tag_id obbligatorio	Riferimento al tag di tracciamento oggetto della richiesta. Tipo: string Esempio: 555j
with_deleted opzionale	Includi nel risultato anche gli elementi eliminati. Tipo: boolean Predefinito: false Valori possibili: true, false

Esempio di richiesta

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

Esempio di risposta

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

Associa un tag di tracciamento alla specifica riga di ordine.

URL della risorsa

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

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro richiesto per tutte le richieste dell’Advertiser API, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Esempio: 18ce54d4x5t
line_item_id obbligatorio	Riferimento alla riga di ordine su cui operi nella richiesta. Type: string Esempio: 8v7jo
tracking_tag_type obbligatorio	Il tipo di tag di tracciamento. Type: enum Valori possibili: IMPRESSION_TAG, CLICK_TRACKER
tracking_tag_url obbligatorio	L’URL del tag di tracciamento fornito dal partner di tracciamento. Type: string Esempio: https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309

Esempio di richiesta

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

Esempio di risposta

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

Associa un tag di tracciamento allo specifico line item.

URL della risorsa

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

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’Advertiser API, escluso GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: 18ce54d4x5t
tracking_tag_url obbligatorio	L’URL del tag di tracciamento fornito dal partner di tracciamento. Tipo: string Esempio: https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309

Esempio di richiesta

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

Esempio di risposta

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

Dissocia un tag di tracciamento dalla voce di riga specificata.

Resource URL

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

Parameters

Name	Description
account_id required	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’Advertiser API, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
tracking_tag_id required	Un riferimento al tag di tracciamento con cui operi nella richiesta. Type: string Example: 555j

Example Request

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

Example Response

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

​

Impostazioni dell’utente

Apri in Postman

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

​

GET accounts/:account_id/user_settings/:user_id

Recupera le impostazioni utente.

URL della risorsa

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

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’Advertiser API, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Esempio: 18ce54d4x5t
user_id obbligatorio	Riferimento all’utente con cui operi nella richiesta. Usa GET users/lookup per recuperare lo user ID a partire da uno screen name. Type: long Esempio: 756201191646691328

Esempio di richiesta

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

Esempio di risposta

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

Aggiorna le impostazioni utente. Richiede il contesto utente. Non accessibile agli amministratori dell’account.

URL della risorsa

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

Parametri

Nome	Descrizione
account_id obbligatorio	Identificatore dell’account utilizzato. Compare nel percorso della risorsa e in GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: 18ce54d4x5t
user_id obbligatorio	Riferimento all’utente con cui operi nella richiesta. Usa GET users/lookup per recuperare un id utente a partire da uno screen name. Tipo: long Esempio: 756201191646691328
notification_email facoltativo	Email da utilizzare per le notifiche dell’account. Tipo: string Esempio: [e-mail]
contact_phone facoltativo	Numero di telefono di contatto. Tipo: string Esempio: 202-555-0128
contact_phone_extension facoltativo	Interno per contact_phone. Tipo: string Esempio: 1234

Esempio di richiesta

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

Esempio di risposta

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