Gerenciamento de Campanhas

​

API de Anunciantes

Agende campanhas de forma programática e gerencie anúncios no X por meio deste conjunto de APIs.

​

O que você pode promover?

​

Promoted Ads

• Promoted Ads são anúncios comuns comprados por anunciantes que desejam alcançar um grupo mais amplo de usuários ou estimular o engajamento dos seguidores existentes.
• Promoted Ads são claramente identificados como Promoted quando um anunciante está pagando por sua veiculação no X. Em todos os outros aspectos, Promoted Ads funcionam como anúncios comuns e podem ser repostados, receber respostas, receber likes e mais. Eles seguem regras típicas de entrega e são criados usando POST statuses/update.
• Tweets “Promoted-only”, criados via POST accounts/:account_id/tweet, podem ser usados em campanhas de Promoted Tweets, mas não serão exibidos para seguidores nem aparecerão na timeline pública. Para recuperar uma lista de tweets apenas promovidos de uma determinada conta, use GET accounts/:account_id/scoped_timeline.

​

Promoted Accounts

• Promoted Accounts fazem parte de Who to Follow, que sugere contas que as pessoas ainda não seguem e podem achar interessantes. Promoted Accounts ajudam a apresentar uma variedade ainda maior de contas que as pessoas podem gostar.
• Promoted Accounts para a Timeline associam um Promoted Tweet a uma campanha de Promoted Account e são exibidas nas timelines dos usuários.

Promoted Trends não estão disponíveis na X Ads API.

​

Campanhas e Grupos de Anúncios (Itens de Linha)

As campanhas definem o cronograma e o orçamento de um anúncio. O anunciante especifica um orçamento diário e um orçamento total. A campanha pode estar vinculada a um horário específico de início e término ou rodar continuamente até que o orçamento seja consumido. O orçamento vem de um dos Funding Instruments da conta de publicidade. Os identificadores de campanha (:campaign_id) são a representação em base 36 do valor em base 10 exibido na X Ads UI.

As contas de publicidade estão limitadas a, no máximo, 200 campanhas ativas. Esse limite pode ser elevado manualmente para 4.000 campanhas ativas pelo X Account Manager do anunciante, mediante solicitação. Uma campanha é considerada ativa até atingir seu horário de término ou ser excluída. Campanhas em pausa são consideradas ativas até seus horários de término designados.

Os itens de linha consomem o orçamento definido por uma campanha. Os itens de linha reúnem o lance por engajamento, o Tweet ou a conta a ser promovida e as regras de segmentação.

​

Analytics

A X Ads API oferece um conjunto de endpoints de analytics para acompanhar e otimizar o desempenho dos anúncios. Consulte Analytics e Analytics Best Practices para mais informações.

Para a métrica de cobrança, os data podem não estar finalizados até três dias após o evento. Antes desse prazo, os data devem ser considerados provisórios. O número final faturável será sempre menor que o valor provisório. O número faturável é ajustado para spam e tráfego relacionado de baixa qualidade. Veja Timezones para outras considerações relacionadas ao tempo.

​

Criando uma campanha - passo a passo

O exemplo a seguir pressupõe que você instalou, configurou e autorizou sua App e seu usuário usando o twurl. O twurl é uma ferramenta de linha de comando, semelhante ao cURL, que lida de forma eficiente com a autenticação OAuth do X. O twurl é ótimo para testar rapidamente e depurar funcionalidades da X Ads API (e da REST API). Para ver todos os cabeçalhos da requisição e da resposta, use -t para rastrear a chamada, opção aproximadamente equivalente ao -v do cURL.

Para este exemplo, criaremos uma campanha de Promoted Ads segmentada por palavra-chave.

1. Recupere o id da conta.

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

{
  "request": {
    "params": {
    }
  },
  "data": [
    {
      "name": "Conta de teste para @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. Recupere o id do instrumento de financiamento.

Faça uma chamada à API GET accounts/:account_id/funding_instruments usando o id da conta obtido no comando anterior.

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. Crie uma campanha e associe-a ao instrumento de financiamento.

Especifique um horário de início e um orçamento para a campanha. Para este exemplo, usaremos um orçamento de US$500 e um limite diário de US$ 50.

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

4. Crie um item de linha associado à campanha.

Agora que temos um id de campanha, podemos criar um item de linha para associá-lo a ela. O item de linha reúne o preço do lance, o direcionamento e a parte criativa da campanha. Para este item de linha, promoveremos tweets com um lance de US$ 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": "Sem título",
    "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. Crie um perfil de segmentação associado ao item de linha.

Com o item de linha criado, podemos definir critérios de segmentação. Queremos direcionar as palavras-chave da frase “grumpy cat” na região da Baía de San Francisco. Isso exigirá uma consulta do id de localização e duas solicitações POST para 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, EUA",
      "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": "São Francisco-Oakland-San José CA, EUA",
    "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. Por fim, retome o item de linha (remova a pausa).

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

É isso! Agora temos uma campanha de Tweets Promovidos em Timelines ativa, segmentada, financiada e em execução.

​

Campanhas baseadas em objetivo

Campanhas e precificação baseadas em objetivo permitem que anunciantes paguem pelas ações alinhadas aos seus objetivos de marketing. Para isso, defina o objective apropriado nos itens de linha.

O parâmetro usado nos endpoints de escrita de itens de linha e retornado nos endpoints de leitura é objective. Atualmente, este campo pode ter os seguintes valores:

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

Os objetivos impactam como otimizamos as campanhas em nossos leilões e como fazemos a cobrança dessas campanhas. Oferecemos precificação baseada no objetivo, como CPAC para APP_ENGAGEMENTS, CPAC ou CPI para APP_INSTALLS, CPLC para WEBSITE_CLICKS, CPF para FOLLOWERS, CPE para ENGAGEMENTS e CPM para REACH.

Campanhas de promoção de app para dispositivos móveis devem conter o objetivo APP_ENGAGEMENTS ou APP_INSTALLS.

Observação: Itens de linha com objetivos diferentes não são permitidos na mesma campanha.

Objetivo da campanha	Objetivo na API	Mídia em Tweets	Modelo de precificação
Reengajamento de app	APP_ENGAGEMENTS	Cartão de download de app em imagem ou vídeo obrigatório.	CPAC
Instalações de app	APP_INSTALLS	Cartão de download de app em imagem ou vídeo obrigatório.	CPAC ou CPI (definido com charge_by)
Alcance	REACH	Sem restrições.	CPM
Seguidores	FOLLOWERS	Tweet não obrigatório, mas recomendado. Não há restrições de mídia em Tweets para campanhas de Seguidores, embora recomendemos Tweets somente de texto. Mais informações	CPF
Engajamentos	ENGAGEMENTS	Sem restrições.	CPE
Visualizações de vídeo	VIDEO_VIEWS	Cartão de conversa em vídeo, vídeo ou GIF obrigatório.	CPV ou custo por visualização de 3s/100%
Visualizações de pre-roll	PREROLL_VIEWS	Vídeo obrigatório.	CPV ou custo por visualização de 3s/100%
Cliques no site	WEBSITE_CLICKS	Cartão de site recomendado, mas não obrigatório. O Tweet deve ter um cartão de site ou um link para o site (não ambos).	CPLC

​

Instrumentos de financiamento

Os instrumentos de financiamento são a fonte do orçamento da campanha. Eles não podem ser criados pela X Ads API; precisam já estar configurados pelo gerente de conta do anunciante na X (para linhas de crédito) ou via ads.x.com (para cartões de crédito) para ficarem disponíveis.

Para obter a lista de todos os funding_instruments de uma conta, consulte GET accounts/:account_id/funding_instruments e, para detalhes de um específico, GET accounts/:account_id/funding_instruments/:funding_instrument_id.

​

Atributos do Instrumento de Financiamento

Descritivos: account_id, id do instrumento de financiamento, type do instrumento de financiamento, description e io_header (ID do cabeçalho da ordem de inserção). Observe que um único io_header pode estar associado a vários instrumentos de financiamento.

Capacidade de financiamento: able_to_fund e reasons_not_able_to_fund.

Tempo: created_at, updated_at, start_time e end_time, representados por uma string no formato “%Y-%m-%dT%l:%M:%S%z”.

Status booleano: paused, deleted e cancelled (true ou false).

Financeiros: currency (formato ISO-4217), credit_limit_local_micro, credit_remaining_local_micro e funded_amount_local_micro. O valor de uma moeda é representado em micros. Para USD, US$ 5,50 é codificado como 5,50*1e6, ou 5.500.000. Para representar um “valor inteiro”, é necessário multiplicar o valor em micros local por 1e6 (1_000_000) para todas as moedas.

​

Detalhes do atributo

credit_limit_local_micro é válido apenas para instrumentos de financiamento do tipo CREDIT_CARD ou CREDIT_LINE e representa o limite de crédito desse instrumento.

funded_amount_local_micro é válido apenas para instrumentos de financiamento do tipo INSERTION_ORDER e representa o orçamento alocado.

credit_remaining_local_micro é válido para instrumentos de financiamento do tipo CREDIT_LINE e AGENCY_CREDIT_LINE. Ele representa o credit_limit_local_micro menos o valor já gasto nesse instrumento de financiamento. Não representa a diferença entre funded_amount_local_micro e o valor gasto. Fazemos uma distinção entre limite de crédito e valor financiado porque eles correspondem a diferentes métodos de financiamento subjacentes e a acordos de gasto que mantemos com os anunciantes.

​

Tipos de Instrumentos de Financiamento

Cartões de crédito

Normalmente usados por anunciantes de autoatendimento (sem um gerente de contas).

Linhas de crédito

São estabelecidas por meio de ordens de inserção (IOs) e definidas por gerentes de contas.

Linhas de crédito multi-handle

Os anunciantes podem financiar campanhas em vários handles com esse tipo de linha de crédito. Esse recurso é habilitado pelo X Account Manager, associando os diferentes @handles a uma linha de crédito específica.

Por exemplo, @NikeSB e @NikeFuel podem ambos ter acesso à linha de crédito @Nike. Esse instrumento de financiamento está disponível como qualquer outro. Você obtém os data enviando uma solicitação GET para o endpoint funding_instrument. Aqui está uma resposta de exemplo (observe o 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 - Linha de Crédito",
            "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
}

A única particularidade deste instrumento de financiamento é o type e o fato de estar disponível para todas as contas a ele associadas. É claro que o crédito restante é impactado por todas as campanhas financiadas por esse instrumento, em todas as contas que o compartilham. Os detalhes sobre quais contas estão associadas a uma linha de crédito específica não estão disponíveis pela API (nem pelo ads.x.com).

Para mais informações sobre enumerações de Funding Instrument, clique aqui.

​

Segmentação

A segmentação é um conceito fundamental da X Ads API. Ela é definida no nível do line item e as opções variam conforme a posição de veiculação. Para definir novos critérios de segmentação, use POST accounts/:account_id/targeting_criteria e PUT accounts/:account_id/targeting_criteria para atualizá-los.

Use GET accounts/:account_id/line_items para obter a lista de todos os line items e GET accounts/:account_id/line_items/:line_item_id para recuperar um line item específico.

​

Opções de segmentação por posicionamento

Os produtos Promoted Tweets e Promoted Accounts podem ser disponibilizados em uma variedade de posicionamentos. Promoted Trends (PTr) não estão disponíveis via a API.

Para possíveis combinações de posicionamento, consulte o endpoint GET line_items/placements. Cada posicionamento tem opções de segmentação diferentes. Localização, Plataforma e Gênero estão disponíveis para todos. As demais opções são contextuais ao tipo de posicionamento.

• X Search: Segmentação por idade, Dispositivos, Eventos, Gênero, Tipos de palavra‑chave (todos), Idioma, Localizações, Ativação de rede, Operadoras de rede, Plataforma, Versão da plataforma, Audiências personalizadas, Somente Wi‑Fi
• X Timeline: Segmentação por idade, Dispositivos, Eventos, Seguidores de, Semelhantes a seguidores de, Gênero, Interesses, Idioma, Localizações, Ativação de rede, Operadoras de rede, Tipos de palavra‑chave não exata, Tipos de audiência de parceiros, Plataforma, Versão da plataforma, Tipos de retargeting, Audiências personalizadas, Tipos de segmentação por TV, Somente Wi‑Fi
• X Profiles & Tweet Details: Segmentação por idade, Dispositivos, Eventos, Seguidores de, Semelhantes a seguidores de, Gênero, Interesses, Idioma, Localizações, Ativação de rede, Operadoras de rede, Tipos de palavra‑chave não exata, Tipos de audiência de parceiros, Plataforma, Versão da plataforma, Tipos de retargeting, Audiências personalizadas, Tipos de segmentação por TV, Somente Wi‑Fi

​

Entendendo os tipos de segmentação

Segmentação por idade: Segmente usuários com base em faixas etárias específicas. Uma lista de enums de faixas etárias pode ser encontrada na página de Enumerações.

Eventos: Especifique um evento para segmentação. Apenas um evento pode ser usado para segmentação (por item de linha). Use o endpoint GET targeting_criteria/events para encontrar eventos disponíveis para segmentação.

Gênero: Segmente homens (1) ou mulheres (2). Deixe como null para segmentar todos.

Categorias da App Store instaladas: use este tipo de segmentação para atingir usuários com base nas categorias de apps que eles instalaram ou demonstraram interesse. Consulte GET targeting_criteria/app_store_categories.

Interesses: Segmente usuários por interesse. Obtenha a lista de interesses em GET targeting_criteria/interests. Você pode segmentar até 100 interesses.

Seguidores de: Segmente os seguidores de quaisquer usuários totalmente promovíveis para a conta atual (observe que, no momento, o titular principal da conta é o único usuário totalmente promovível dessa conta). Use GET accounts/:account_id/promotable_users para obter uma lista de usuários promovíveis.

Semelhante a Seguidores de: Almeje pessoas com os mesmos interesses que os seguidores de usuários específicos. Você pode usar até 100 Users.

Localizações: Especifique até 2.000 localizações para segmentar. Obtenha a lista em GET targeting_criteria/locations. Há requisitos adicionais para anúncios que segmentam determinados países. Consulte Requisitos de segmentação por país e exibição para mais informações.

Palavras-chave: As opções de segmentação por palavra-chave variam conforme o tipo de posicionamento. Você pode usar até 1.000 palavras-chave para segmentação (por item de linha). Consulte a seção Tipos de palavra‑chave para opções.

Segmentação por idioma: Segmente usuários que entendem idiomas específicos.

Segmentação por operadora de rede móvel: Permite que anunciantes segmentem usuários com base na operadora móvel, usando o tipo de segmentação NETWORK_OPERATOR de GET targeting_criteria/network_operators.

Segmentação por novo dispositivo móvel: Alcance usuários com base na data em que acessaram o X pela primeira vez via seu dispositivo, usando o tipo de segmentação NETWORK_ACTIVATION_DURATION e o operator_type LT para menor que e GTE para maior ou igual.

Plataformas, Versões de plataforma, Dispositivos e Somente Wi‑Fi: Permite a segmentação de dispositivos móveis em diversos vetores. Plataformas é um tipo de segmentação de alto nível que pode atingir categorias amplas de telefones. Exemplos de valores: iOS e Android. Dispositivos permitem segmentar usuários de dispositivos móveis específicos, por exemplo iPhone 5s, Nexus 4 ou Samsung Galaxy Note. Versões de plataforma permitem segmentar usuários de versões de sistemas operacionais móveis específicos, até a release pontual. Exemplos incluem iOS 7.1 e Android 4.4. Somente Wi‑Fi permite segmentar apenas os usuários que estão usando seus dispositivos em uma rede Wi‑Fi; se isso não estiver definido, usuários usando a conexão da operadora, assim como Wi‑Fi, serão segmentados.

• Usuários podem segmentar plataformas e dispositivos se não houver sobreposição. Posso segmentar BlackBerry como plataforma e iPad Air como dispositivo simultaneamente.
• Usuários podem segmentar dispositivos e versões de SO simultaneamente. Posso segmentar iPad Air e iOS >= 7.0.
• Usuários não podem segmentar plataformas que sejam mais amplas do que dispositivos. Não posso segmentar iOS e iPad Air.

[Tailored Audiences]/x-ads-api/audiences: Alcance usuários por meio de um parceiro de anúncios aprovado para segmentar grupos de clientes e se conectar com eles no X.

TV Targeting

Segmentação por programa de TV: alcance pessoas que interagem com programas de TV específicos. Esse critério de segmentação pode ser configurado para continuar ativo enquanto a campanha estiver em execução, usando o tipo de segmentação TV_SHOW. Use os endpoints GET targeting_criteria/tv_markets e GET targeting_criteria/tv_shows para identificar os programas de TV disponíveis.

Retargeting de engajadores de Tweet

O retargeting de engajadores de Tweet permite que anunciantes segmentem públicos em vários dispositivos que foram previamente expostos ou engajaram com seus Tweets promovidos ou orgânicos no X. Com essa segmentação, os anunciantes podem fazer follow-up com pessoas que viram ou engajaram com o conteúdo do anunciante no X e que têm maior probabilidade de continuar engajando ou converter diante de mensagens ou ofertas subsequentes. Os usuários se tornam elegíveis para segmentação em poucos minutos após a exposição ou o engajamento e permanecem elegíveis por até 90 dias após engajamentos e 30 dias após exposições.

Tipos de segmentação de engajadores de Tweet:

• ENGAGEMENT_TYPE, que aceita IMPRESSION ou ENGAGEMENT como valor de segmentação. Isso especifica se você deseja segmentar usuários expostos (IMPRESSION) ou usuários engajados (ENGAGEMENT).
• CAMPAIGN_ENGAGEMENT usa um id de campanha como valor de segmentação. Usuários que engajaram ou foram expostos a essa campanha (dependendo de ENGAGEMENT_TYPE) são os que serão segmentados.
• USER_ENGAGEMENT, que usa o id do usuário promovido como valor de segmentação para atingir usuários que foram expostos ou engajaram com conteúdo orgânico de um anunciante (dependendo de ENGAGEMENT_TYPE). Deve ser o id do usuário promovido associado à conta de Ads.

Nota: ENGAGEMENT_TYPE é obrigatório, além de pelo menos um valor válido de CAMPAIGN_ENGAGEMENT ou USER_ENGAGEMENT. Ambos os tipos de segmentação de engajadores de Tweet podem estar presentes e várias campanhas podem ser segmentadas em um determinado item de linha.

Segmentação de espectadores de vídeo: a segmentação de espectadores de vídeo se baseia na segmentação de engajadores de Tweet para permitir que anunciantes segmentem públicos que anteriormente assistiram a parte ou a todo um vídeo no X. Os anunciantes podem segmentar vídeos orgânicos, vídeos promovidos ou ambos. Vídeos promovidos não se limitam a campanhas ou itens de linha com objetivo de visualização de vídeo.

Tipos de segmentação de espectadores de vídeo:

• VIDEO_VIEW para usuários que clicaram para reproduzir o vídeo ou visualizaram 3 segundos de reprodução automática
• VIDEO_VIEW_PARTIAL para usuários que visualizaram 50% do vídeo
• VIDEO_VIEW_COMPLETE para usuários que visualizaram pelo menos 95% do vídeo

Assim como na segmentação de engajadores de Tweet, um ou ambos os seguintes também devem estar presentes nos critérios de segmentação do item de linha quando ENGAGEMENT_TYPE for usado:

• CAMPAIGN_ENGAGEMENT usa um id de campanha como valor de segmentação. Usuários que assistiram a um vídeo (com base em ENGAGEMENT_TYPE) nesta campanha são os que serão segmentados.
• USER_ENGAGEMENT, que usa o id do usuário promovido como valor de segmentação para atingir usuários que assistiram a um vídeo (com base em ENGAGEMENT_TYPE) em conteúdo orgânico de um anunciante. Deve ser o id do usuário promovido associado à conta de Ads.

Tipos de palavra-chave

Consulte nosso documento de suporte sobre keyword targeting para uma visão conceitual.

• Ampla (valor padrão): corresponde a todas as palavras, independentemente da ordem. Não é sensível a maiúsculas/minúsculas, plurais ou tempo verbal. Será automaticamente expandida quando possível (por exemplo, “car repair” também corresponderia a “automobile fix”). Se quiser segmentar sem expansão, adicione um sinal de + antes das palavras-chave, como “+boat +jet”. Usar palavras-chave sem o + aplica a Correspondência Ampla por padrão.
• Desordenada (descontinuada): corresponde a todas as palavras, independentemente da ordem. Não é sensível a maiúsculas/minúsculas, plurais ou tempo verbal.
• Frase: corresponde exatamente à string de palavras-chave; outras palavras-chave podem estar presentes.
• Exata: corresponde exatamente à string de palavras-chave, e nenhuma outra.
• Negativa: evita corresponder a pesquisas que incluam todas essas palavras-chave em algum lugar na query, independentemente da ordem em que forem escritas, mesmo que outras palavras estejam presentes.
• Frase negativa: evita corresponder a pesquisas que incluam exatamente essa string de palavras-chave em algum lugar na query, mesmo que outras palavras estejam presentes.
• Exata negativa: evita corresponder a pesquisas que correspondam exatamente a essas palavras-chave e não contenham outras palavras.  

Segmentação por emoji

O direcionamento por emoji é compatível por meio do direcionamento por palavra-chave. Para usá-lo, basta criar um direcionamento por palavra‑chave para os code points Unicode que representam esse emoji, como U+1F602 (xF0x9Fx98x82 em UTF-8) para o emoji “face with tears of joy” (😂). Os emojis aceitos podem ser confirmados na lista twemoji. Direcionar um emoji abrange todas as suas variações.

Para um resumo de todos os valores com indicações de obrigatório/opcional e detalhes específicos de cada um, consulte PUT accounts/:account_id/targeting_criteria.

​

Combinações de critérios de segmentação

Fluxo de trabalho de campanha atualizado

Crie campanhas com segmentação ampla usando critérios de região, gênero, idioma e dispositivo/plataforma. Os anunciantes podem então combinar essa segmentação ampla com critérios adicionais (por exemplo, interesses, palavras-chave, seguidores, audiências personalizadas, TV). Se nenhum critério de segmentação for especificado para um item de linha, o item de linha segmentará todos os usuários no mundo todo.

Tipos “Primários”	Outros tipos
Seguidores	Localizações
Audiências personalizadas	Gênero
Interesses	Idiomas
Palavras-chave	Dispositivos e plataformas
TV	Idade

Os critérios de segmentação serão combinados para o seu grupo de anúncios da seguinte forma:

• Tipos de segmentação “Primários” serão unidos com ∪ (ou seja, em uma união lógica).
• Outros tipos de segmentação serão combinados com AND.
• Tipos iguais serão combinados com OR.

Alguns exemplos

Em resumo: [(Seguidores) ∪ (Audiências personalizadas) ∪ (Interesses) ∪ (Palavras-chave)] AND (Localização) AND (Gênero) AND (Idiomas) AND (Dispositivos e plataformas)

Um exemplo geográfico:

Digamos que queremos que um grupo de anúncios da nossa campanha tenha a seguinte segmentação:

• usuários do X nos EUA, Inglaterra e Canadá (Localização)
• que sejam mulheres (Gênero)
• provenientes de lista de Audiências personalizadas (“Primário”)
• com Palavras-chave (“Primário”)

Os critérios de segmentação serão:

[US OR GB OR CA] AND [Female] AND [Audiências personalizadas ∪ Palavras-chave]

​

Exemplos adicionais

• Selecionar gênero e localização, mas sem primário: (Masculino) AND (US OR GB)
• Selecionar gênero, localização, interesse: (Feminino) AND (CA) AND (Computers OR Technology OR Startups)
• Selecionar gênero, localização, interesse, Tailored Audiences, palavras-chave: (Masculino) AND (GB) AND (Cars ∪ Tailored Audiences for CRM ∪ autocross)

​

Ritmo de gasto do orçamento

Os anunciantes agora têm mais controle sobre a rapidez com que seus orçamentos diários são utilizados em campanhas de Tweet Promovido e de Conta. Ativar a entrega padrão, que é a opção padrão, garante uma taxa de gasto uniforme ao longo do dia.

Ao desativar a entrega padrão, exibiremos impressões e geraremos engajamentos o mais rápido possível até que seu orçamento diário se esgote, o que pode acontecer bem cedo no dia, dependendo do direcionamento e da concorrência. Isso é chamado de entrega acelerada.

Como começar

A entrega padrão é a opção padrão para todas as campanhas, portanto, nenhuma ação é necessária, a menos que você deseje desativá-la. Para consumir seu orçamento diário em uma campanha o mais rápido possível, defina o parâmetro standard_delivery como false para ajustar o ritmo para entrega acelerada (veja GET accounts/:account_id/campaigns).

Notas

• “Dia” é relativo ao fuso horário da conta de anunciante da X (por exemplo, America/Los_Angeles).
• Resultados iniciais indicam que a entrega padrão melhora o eCPE/CPF para os anunciantes, com cobertura mais consistente ao longo do dia.

Para informações adicionais sobre orçamentos e ritmo, consulte as perguntas frequentes sobre lances e leilões.

​

Lance direcionado

Gerenciamento de campanhas

​

Estratégia de Lance

Introduzimos o conceito de Estratégia de Lance para simplificar o fluxo de criação de campanhas e reduzir a confusão sobre combinações de vários parâmetros.

Todas as combinações anteriores (marcadas como legadas) de parâmetros podem ser obtidas definindo um parâmetro de meta equivalente. Mais informações podem ser encontradas no anúncio aqui.

Como exemplo:

Objetivo da campanha	Legado	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 (Observação: bid_unit não era necessário para alguns objetivos de campanha)	bid_strategy = TARGET

​

Lance por meta

Com o lance por meta, você pode especificar um custo-alvo que deseja pagar e a plataforma X Ads otimizará sua campanha para desempenho, mantendo-se próxima ou abaixo desse custo-alvo.

Esse recurso oferece flexibilidade para alcançar usuários com maior probabilidade de realizar a ação desejada (como um clique no link, um lead ou um follow), mantendo o controle de custos. É um recurso poderoso para anunciantes que desejam mais opções de configuração e otimização de campanhas (incluindo opções de lance).

Para itens de linha com objetivos de campanha compatíveis, introduzimos um novo mecanismo de precificação para o valor do lance que permite especificar um custo-alvo a pagar. Nossa plataforma de anúncios faz lances dinamicamente em seu nome para ajudar você a obter mais resultados, trabalhando para manter seu custo médio dentro de 20% do alvo especificado. A configuração bid_strategy nos itens de linha pode ser definida com o valor TARGET para habilitar o lance por meta em objetivos de campanha relevantes, como:

• WEBSITE_CLICKS
• WEBSITE_CONVERSIONS
• APP_INSTALLS
• APP_ENGAGEMENTS
• REACH

​

Requisitos de segmentação e exibição por país

Gerenciamento de campanhas

Os requisitos específicos por país para segmentação e exibição estão descritos nesta página. Todos os parceiros devem cumprir esses requisitos.

​

Rússia

As políticas de anúncios da X proíbem que anunciantes segmentem a Rússia com anúncios que não estejam em russo. Quando seus usuários segmentarem especificamente a Rússia, você deve exibir a seguinte mensagem de aviso aos seus usuários:

Anúncios direcionados à Rússia devem estar em russo.

​

Instrumentos de financiamento gerenciados pelo parceiro

O fluxo de integração configura uma conta no ads.x.com para a conta X, que pode ser gerenciada pelo parceiro por meio da X Ads API, e cujos gastos com publicidade são faturados ao parceiro.  

​

Configuração inicial do parceiro

O processo para configurar um novo parceiro PMFI Ads API leva até 3 semanas a partir da troca das informações necessárias. Para iniciar o processo, compartilhe o seguinte com seus contatos técnicos na X, bem como com o contato da X que gerencia a integração com o parceiro:

• O parceiro deve compartilhar sua chave pública PGP/GPG. Uma chave secreta compartilhada precisa ser trocada entre o parceiro da Ads API e a X. Ela será usada para verificar os dados durante o fluxo de onboarding.
• O app_id ou consumer_secret da X App que será usada para acesso à Ads API. Você pode visualizar e editar suas X Apps existentes por meio do app dashboard se estiver conectado à sua conta X em developer.x.com. Se precisar criar uma X App, você precisará ter uma conta de desenvolvedor aprovada. A X permite uma App para produção+sandbox e uma App opcional apenas para sandbox. A X App deve ser criada em um handle corporativo controlado pelo parceiro.  

​

Fluxo de onboarding de anunciantes

O fluxo de onboarding de anunciantes ocorre em um navegador da web da seguinte forma:

1. O usuário inicia o fluxo de onboarding no site do parceiro e informa o handle que deseja onboardar.
2. O parceiro redireciona o usuário para uma URL em ads.x.com com um payload assinado. Esse payload contém o app_id de API do parceiro, o user_id da X referente ao handle da X que será onboardado, além de uma URL de callback e outros fields documentados abaixo.
3. Solicita-se que o usuário faça login em ads.x.com usando a página de login padrão do x.com.
4. Após o login do usuário, o processo de onboarding é iniciado. Esta etapa inclui análise de anúncios, validação de conta e outras verificações.
5. Quando todas as tarefas de onboarding forem concluídas, o usuário é redirecionado para a URL de callback fornecida pelo parceiro da X Ads API, com um payload que indica sucesso ou falha. Isso inclui o processo de autorização em 3 etapas.  

​

Payload de redirecionamento de onboarding

URL para redirecionamento:

https://ads.x.com/link_managed_account

A URL de redirecionamento será chamada com os seguintes parâmetros:

Nome	Tipo	Descrição
callback_url	string codificada em URL	o usuário será redirecionado para esta URL após a conclusão do processo de vinculação da conta, independentemente do resultado. Consulte a seção de URL de redirecionamento do parceiro para detalhes do protocolo
client_app_id	integer	id da App cliente da X API, usado para identificar o parceiro gestor
promotable_user_id	integer	id de usuário da X do @handle cujas promoções serão gerenciadas pelo parceiro gestor. Usado para garantir que seja o mesmo usuário que faz login em ads.x.com para concluir o processo de vinculação
fi_description	string codificada em URL (máx. 255 caracteres)	nome do instrumento de financiamento. Isso será exibido no campo de descrição na API quando o instrumento de financiamento for recuperado. Se uma descrição de funding_instrument for fornecida, o funding_instrument existente será pausado e um novo instrumento de financiamento do parceiro gestor será configurado. (se já existir um com o mesmo nome, nada acontecerá)
timezone	string no formato Area/Location	Fuso horário que será usado para determinar o dia ao qual os orçamentos diários se aplicam e no qual as cobranças serão agregadas
currency	Código de moeda ISO 4217	Moeda que será usada para inserir lances e na qual as cobranças serão faturadas
country	Código de país ISO 3166-1 alpha 2	País de cobrança da conta
signature	código binário codificado em URL e em base64, conforme explicado abaixo	assinatura que combina um segredo compartilhado e os demais parâmetros para verificar a autenticidade da chamada, bem como a validade dos parâmetros.

​

Payload da URL de callback

A URL base de redirecionamento é fornecida usando o parâmetro callback_url na solicitação de vinculação de conta (veja acima). Os parâmetros adicionados por ads.x.com são:

Nome	Tipo	Descrição
status	string	OK uma conta foi criada ou uma conta existente e elegível foi encontrada. ACCOUNT_INELIGIBLE se as restrições específicas do parceiro não forem atendidas USER_MISMATCH a conta do X usada para entrar em ads.x.com era diferente do promotable_user_id na solicitação de vinculação de conta INCOMPLETE_SERVING_BILLING_INFO fuso horário, moeda ou país não foram especificados INVALID_COUNTRY foi fornecido um valor de país inválido INVALID_CURRENCY foi fornecido um valor de moeda inválido INVALID_TIMEZONE foi fornecido um valor de fuso horário inválido
account_id	string codificada em URL	id da conta de anúncios do X da conta vinculada
funding_instrument_id	string codificada em URL	id do instrumento de financiamento gerenciado pelo parceiro ativo
signature	código binário codificado em URL e em base64, conforme explicado abaixo	Assinatura HMAC-SHA1 codificada em Base64 que combina um segredo compartilhado e os demais parâmetros para verificar a autenticidade da chamada, bem como a validade dos parâmetros. Para garantir que a URL de callback seja válida apenas para o X user_id para o qual o processo de vinculação de conta foi destinado, o X user_id deve ser anexado ao segredo compartilhado (usando &) ao assinar a solicitação.

Para garantir que a URL de callback seja válida apenas para o X user_id para o qual o processo de vinculação de conta foi destinado, o X user_id deve ser anexado ao segredo compartilhado (usando &) ao assinar a solicitação.  

​

Assinando a solicitação e URLs de callback

Para garantir que as solicitações para /link_managed_account e a URL de callback sejam válidas, elas precisam ser assinadas na origem e verificadas pelo destinatário antes que ele tome qualquer ação. Assinar a solicitação com um segredo compartilhado entre X e o parceiro responsável garante que cada parte aceite apenas solicitações enviadas pela contraparte autorizada.

O algoritmo de geração de assinatura é semelhante ao usado no OAuth.

Crie uma string base de assinatura da seguinte forma:

• Converta o método HTTP para maiúsculas e defina a string base como esse valor.
• Acrescente o caractere ‘&’ à string base.
• Faça o percent-encode da URL (sem parâmetros) e acrescente à string base.
• Acrescente o caractere ‘&’ à string base.
• Acrescente a query string com percent-encode, construída da seguinte forma:
• Aplique percent-encode a todas as chaves e valores que serão assinados.
• Ordene a lista de parâmetros alfabeticamente pela chave.
• Para cada par chave/valor (e com primary_promotable_user_id para a URL de redirecionamento do parceiro):
• Acrescente a chave com percent-encode à query string.
• Acrescente o caractere ‘=’ à string base.
• Acrescente o valor com percent-encode à query string.
• Separe os pares chave=valor com percent-encode usando o caractere ‘&’.
• Use o algoritmo HMAC-SHA1, utilizando o segredo compartilhado previamente como a chave e a string base como o valor, para gerar a assinatura.
• Faça o encode em Base64 da saída do Passo 2, remova o caractere de nova linha final, faça o percent-encode da assinatura gerada no Passo 3 e adicione-a à URL no parâmetro signature  

​

Exemplos de assinatura

Assinando uma solicitação de vinculação de conta

URL a ser assinada, considerando uma solicitação 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

Esta URL possui os seguintes parâmetros:

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

A base string, composta pelo método HTTP e pela URL sem parâmetros (etapas a - d), é:

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

A query string, produzida pelas subetapas do item e, é:

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

Observe que os pares chave-valor estão ordenados pelo nome da chave.

A query string com percent-encoding é:

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

A base string completa, combinando as etapas a - d e 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

Usando o algoritmo hmac-sha1, assinaremos isso com a palavra “secret” como chave. O resultado é codificado em Base64 e apresentado sem o “\n” final (etapas 2 e 3): KBxQMMSpKRrtg9aw3qxK4fTXvUc=

Essa assinatura é então adicionada (com percent-encoding) ao final da URL original, no parâmetro de assinatura (etapa 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

Assinando uma URL de redirecionamento do parceiro (callback da solicitação de vinculação de conta) A URL a ser assinada, considerando uma solicitação GET:

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

Esta URL possui os seguintes parâmetros:

account_id = ABC, funding_instrument_id = DEF e status = OK

A base string, composta pelo método HTTP e pela URL sem parâmetros (etapas a - d), é:

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

A query string, produzida pelas subetapas do item e, é:

account_id=ABC&funding_instrument_id=DEF&status=OK

A query string com percent-encoding é:

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

A base string completa, combinando as etapas a - d e e, é:

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

Usando o algoritmo hmac-sha1, assinaremos isso com a palavra “secret” e o id de usuário da X para o qual a solicitação original de vinculação foi feita, 1 (promotable_user_id = 1 acima), como chave: “secret&1”.

O resultado é codificado em Base64 e apresentado sem o “\n” final (etapas 2 e 3): jDSHDkHJIFXpPLVxtA3a9d4bPjM=

Essa assinatura é então adicionada (em percent-encoding) ao final da URL original no parâmetro signature (etapa 4):

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

​

Uso/renovação de Shared Key

O algoritmo de assinatura deve conseguir ser executado repetidamente com várias chaves. Isso permitirá o uso de múltiplas shared keys e viabilizará a rotação periódica dessas chaves.  

​

criação de partner_managed_funding_instrument

Se o parâmetro fi_description for informado e não houver nenhum partner_managed_funding_instrument com o mesmo nome na conta, um novo partner_managed_funding_instrument será criado e todos os partner_managed_funding_instruments existentes serão pausados.

Se já existir um partner_managed_funding_instrument com o mesmo nome, nenhum novo será criado.  

​

Chamadas repetidas do fluxo de onboarding / renovação de token

O fluxo de onboarding pode ser repetido caso o access token da API tenha sido perdido. A implementação do fluxo de onboarding exigirá que o usuário esteja autenticado. Se o usuário corresponder ao promotable_user_id, a conta de anúncios associada for encontrada e tudo estiver correto, o usuário será redirecionado de volta para a URL de callback, e o parceiro poderá iniciar o fluxo OAuth para obter um access token.  

​

Fluxo de erro não redirecionável

Se a URL de vinculação de conta for invocada com parâmetros inválidos, será exibida ao usuário uma página semelhante à apresentada no fluxo do OAuth quando forem fornecidos parâmetros inválidos ou expirados.  

​

Atualizações contínuas do PMFI

Depois que o anunciante for integrado, o instrumento de financiamento poderá ser gerenciado pelo parceiro responsável por meio do endpoint PUT accounts/:account_id/funding_instruments/:funding_instrument_id.

​

Posicionamentos

Há vários locais onde anúncios do X podem ser exibidos. Isso é definido no item de linha usando o parâmetro placements. Os valores possíveis são:

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

Os campos product_type e objective do item de linha determinam quais posicionamentos são permitidos. O endpoint GET line_items/placements pode ser usado para recuperar as opções de posicionamento válidas para cada tipo de produto.

Além disso, a tabela a seguir lista as combinações válidas de posicionamento e objetivo.

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

Observação: Não é possível especificar somente o posicionamento TWITTER_PROFILE.

Observação: TWITTER_SEARCH requer segmentação por palavra‑chave.

Observação: O objetivo REACH deve incluir o posicionamento TWITTER_TIMELINE. Ele pode ter ALL_ON_TWITTER, qualquer combinação de posicionamentos que inclua TWITTER_TIMELINE ou apenas TWITTER_TIMELINE.

​

Perguntas frequentes sobre grupos de anúncios

Este documento reúne perguntas frequentes sobre grupos de anúncios na X Ads API.

​

O que é um grupo de anúncios?

Grupos de anúncios, conhecidos como line items na X Ads API, ficam sob campanhas e são usados para segmentação e lances direcionados a um conjunto de usuários do X. Os anunciantes promovem Tweets ou mídia (por exemplo, vídeos veiculados como anúncios In-stream) ao associá-los a um line item.

​

Como criamos um Ad Group?

Os Ad Groups são criados chamando POST accounts/:account_id/line_items várias vezes para o mesmo id de campanha e mantendo o direcionamento (que pode ser completamente diferente) e os Tweets associados a esses line items. Há um limite de 100 line items por campanha e um limite de 200 campanhas ativas por conta de anúncios. Em todas as campanhas, há um limite de 8.000 line items ativos por conta de anúncios.

​

Por que devemos adicionar suporte a Grupos de Anúncios?

Os Grupos de Anúncios visam facilitar para os anunciantes a organização, a otimização e o gerenciamento de suas campanhas.

A vantagem dos Grupos de Anúncios é permitir comparar e controlar diferentes estratégias de lance, orçamento, criação e segmentação. Ao associar vários Promoted Tweets a um único line item, o leilão selecionará o melhor Tweet desse grupo e, em seguida, selecionará o melhor Tweet para aquela campanha entre todos os line items. Se você tiver vários Grupos de Anúncios com um único Tweet cada, ele selecionará efetivamente o Tweet com maior probabilidade de desempenho superior daquele Grupo de Anúncios.

O uso de Grupos de Anúncios permite que um anunciante divida a segmentação e os lances em um número muito maior de combinações possíveis e, de modo geral, possibilita fracionar a segmentação em grupos lógicos.

Ferramentas da X Ads API, em particular, podem ser desenvolvidas com base em regras de otimização bem ajustadas usando Grupos de Anúncios — algo mais difícil de fazer por meio de edições manuais devido à grande escala de combinações de line item e criativos.

​

Como o orçamento do item de linha se relaciona ao orçamento da campanha em uma campanha de Grupos de Anúncios?

O total_budget_amount_local_micro de um item de linha não pode exceder o orçamento total de sua campanha principal. Da mesma forma, o valor de bid_amount_local_micro do item de linha não deve exceder o daily_budget_amount_local_micro ou o total_budget_amount_local_micro da campanha principal. Definir esses valores incorretamente pode colocar a campanha como um todo em estado pausado e não veiculável.

Observe que o orçamento total da campanha pode ser menor que a soma dos orçamentos de seus itens de linha filhos, e a distribuição do orçamento entre os itens de linha fica, em parte, a critério da ferramenta da X Ads API para otimizar e ajustar de forma eficaz, já que o desempenho diário do direcionamento (item de linha) pode variar significativamente de um dia para o outro devido à natureza em tempo real da X.

​

Os grupos de anúncios têm desempenho melhor do que itens de linha individuais?

O desempenho de uma campanha depende de muitos fatores e, em última análise, o Tweet é o fator decisivo final do desempenho. Um item de linha é tratado como um fator que determina se um Tweet está ou não concorrendo para ser exibido a um usuário.

Itens de linha que segmentam os mesmos conjuntos de usuários são considerados como tendo sobreposição de usuários. É uma prática recomendada reduzir essa sobreposição de segmentação entre itens de linha para que os conjuntos de usuários com melhor desempenho possam ser identificados com clareza.

​

Guias

​

Objetivo de Visualizações de Vídeo em Preroll

O guia a seguir descreve as etapas necessárias para configurar uma campanha PREROLL_VIEWS na X Ads API. De modo geral, essas campanhas se dividem em dois tipos: Categorias Selecionadas e Categorias de Conteúdo (chamadas de Categorias Padrão na interface do Ads).  

​

Endpoints necessários

• Chunked media upload (para envio de vídeo)
• POST accounts/:account_id/media_library (para associar o vídeo à conta de anúncios)
• POST accounts/:account_id/campaigns (criar campanha)
• GET content_categories (para obter o mapeamento de categorias de conteúdo para categorias IAB)
• GET accounts/:account_id/curated_categories
• GET publishers
• POST accounts/:account_id/line_item_curated_categories
• POST accounts/:account_id/line_items (criar grupo de anúncios)
• POST accounts/:account_id/media_creatives (para associar o vídeo ao grupo de anúncios)
• POST accounts/:account_id/preroll_call_to_action (definir CTA e URL de redirecionamento)
• POST batch/accounts/:account_id/targeting_criteria (segmentação)

​

Passos

​

Envie o vídeo

O envio do vídeo envolve 2 etapas:

​

Fazer upload da mídia de vídeo

Primeiro, usando o endpoint Chunked media upload, você fará o upload do vídeo para a X para processamento. Você deve passar media_category=amplify_video no INIT inicial usando esse endpoint. O vídeo será enviado em partes (chunks). Quando o STATUS retornar state como succeeded, você poderá prosseguir com as próximas etapas. Mais informações sobre o envio de mídia em partes usando esse endpoint podem ser encontradas em nossa Visão geral de Promoted Video.

​

Adicione o vídeo à conta de anúncios

Quando o estado retornado pelo comando STATUS for succeeded, use o media_key retornado por esse endpoint para adicionar o vídeo à biblioteca de mídia do anunciante, usando o 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
 }
}

​

Configurar a campanha

​

Criação de campanha

Crie a campanha e o item de linha/grupo de anúncios. Os itens de linha devem ser criados com objective definido como VIDEO_VIEWS_PREROLL e product_type definido como MEDIA. O parâmetro categories também deve ser configurado para as categorias de negócios do anunciante apropriadas.

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

​

Criação de Line Item

Os line items devem ter o parâmetro categories definido com o conjunto apropriado de categorias IAB, obtido por meio do endpoint GET content_categories. Cada uma dessas categorias de conteúdo corresponde a uma ou mais categorias IAB.

Para utilizar esses valores, os parceiros devem selecionar uma categoria de conteúdo apropriada e usar o conjunto completo de iab_categories retornado na resposta para definir o parâmetro categories no endpoint de line items. Qualquer aplicação parcial de iab_categories resultará na definição de todo o grupo no line item. Por exemplo,

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

{
  "request": {
    "params": {}
  },
  "next_cursor": null,
  "data": [
    {
      "id": "1jl",
      "name": "Bens de consumo embalados",
      "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": "Saúde e farmacêutica",
      "iab_categories": [
        "IAB7"
      ]
    },
    {
      "id": "1jn",
      "name": "Álcool",
      "iab_categories": [
        "IAB8-5",
        "IAB8-18"
      ]
    },
    {
      "id": "1jo",
      "name": "Alimentação fora de casa",
      "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": "Serviços financeiros",
      "iab_categories": [
        "IAB3",
        "IAB13",
        "IAB21"
      ]
    },
    {
      "id": "1jq",
      "name": "Varejo",
      "iab_categories": [
        "IAB18"
      ]
    },
    {
      "id": "1jr",
      "name": "Viagens",
      "iab_categories": [
        "IAB20"
      ]
    },
    {
      "id": "1js",
      "name": "Games",
      "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": "Telecomunicações",
      "iab_categories": [
        "IAB19-6",
        "IAB19-18"
      ]
    },
    {
      "id": "1jv",
      "name": "Automotivo",
      "iab_categories": [
        "IAB2"
      ]
    },
    {
      "id": "1jw",
      "name": "Mídia e entretenimento",
      "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": "Política",
      "iab_categories": [
        "IAB11-4"
      ]
    },
    {
      "id": "1jy",
      "name": "Apostas",
      "iab_categories": [
        "IAB9-7"
      ]
    },
    {
      "id": "1jz",
      "name": "Relacionamentos",
      "iab_categories": [
        "IAB14-1"
      ]
    },
    {
      "id": "1k0",
      "name": "Sem fins lucrativos",
      "iab_categories": [
        "IAB11-1",
        "IAB11-2",
        "IAB11-3",
        "IAB11-5"
      ]
    }
  ]
}

Agora, para definir o parâmetro categories como “Science & Education”, é necessário atribuir ao item de linha todo o conjunto de iab_categories, ou seja, “IAB5” e “IAB15”, da seguinte forma:

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

{
  "request": {
    "params": {
      "name": "item-de-linha-de-categoria-curada",
      "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": "item-de-linha-de-categoria-curada",
    "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
  }
}

​

Seleção de Publicadores

Um anunciante pode optar por segmentar uma Content Category ou uma Curated Category, com detalhes adicionais descritos abaixo. 

Observação: Os line items podem segmentar categorias Curated ou Content, mas não ambas. 

​

Categorias Curadas

Categorias Curadas permitem que anunciantes segmentem um grupo predefinido de publishers e podem ser recuperadas usando o endpoint GET curated_categories. Essas categorias são específicas de cada país e, portanto, exigem que o line item segmente o país apropriado com base no country_code da categoria.

Para usar uma dessas categorias, siga as etapas abaixo na ordem indicada:

1. O line item precisa segmentar o país apropriado com base no country_code da Categoria Curada
2. O endpoint POST line_item_curated_categories deve ser usado para associar o line item a um curated_category_id específico. 

Observação: Associar um line item a uma categoria curada também limitará a 5 o número de publishers que podem ser adicionados à denylist. A lista completa de user_id usados para colocar publishers específicos em denylist pode ser recuperada pelo endpoint GET publishers. Além disso, um determinado line item pode segmentar no máximo uma Categoria Curada por vez.

O exemplo a seguir ilustra como associar um id de categoria curada: b0xt, disponível apenas nos EUA, ao line item criado na etapa anterior.

Primeiro, os critérios de segmentação do line item são definidos para o valor 96683cc9126741d

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

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

​

Categorias de conteúdo

As categorias de conteúdo, também chamadas de Categorias Padrão, podem ser obtidas pelo endpoint GET curated_categories. Essas categorias podem então ser segmentadas pelo line item usando os endpoints de critérios de segmentação em lote. O exemplo a seguir mostra como selecionar uma categoria de conteúdo específica, id: sr, que corresponde a “News & Current Events”, e aplicá-la ao line item.

Observação: Todo o conjunto de iab_categories na resposta de GET curated_categories deve ser segmentado por meio do endpoint de critérios de segmentação. Caso contrário, ocorrerá um erro de validação.

GET https://ads-api.x.com/8/content_categories
{
      "name": "Notícias e eventos atuais",
      "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": "Notícias",
      "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": "Sociedade"
      "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"
    }
  \]
}

Associar a mídia da conta (vídeo) ao item de linha

Use o endpoint POST accounts/:account_id/media_creatives para associar o vídeo a um grupo de anúncios.

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

​

Defina a CTA e a URL de destino

É importante observar que, diferentemente da maioria das outras campanhas no X, o objetivo VIDEO_VIEWS_PREROLL não utiliza Tweets promovidos ou Cards. Em vez disso, o vídeo criativo é associado ao seu grupo de anúncios (line item) e as informações da CTA são associadas a uma entidade preroll_call_to_action. O endpoint POST accounts/:account_id/preroll_call_to_action permite controlar o botão de CTA e a URL de destino.

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":"ASSISTIR_AGORA",
   "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":"VISITAR_O_SITE",
     "call\_to\_action_url":"https://x.com/AdsAPI"
   }
 }
}

​

Definir critérios de segmentação

O critério de segmentação usado para anúncios em vídeo pre-roll está disponível apenas por meio do nosso endpoint de critérios de segmentação em lote POST batch/accounts/:account_id/targeting_criteria.

Use CONTENT_PUBLISHER_USER como segmentação negada para impedir que o anúncio seja associado a um conjunto de usuários. Forneça o user_id da X ou o publisher_user_id dos @handles a serem excluídos.

O endpoint GET publishers pode ser usado para recuperar a lista de user_id a serem excluídos para Categorias de Conteúdo. O publisher_user_id retornado na resposta de GET curated_categories pode ser usado para recuperar uma lista de exclusão semelhante para Categorias Curadas.

Observação: No máximo 5 publisher_user_id podem ser excluídos para Categorias Curadas e 50 user_id para Categorias de Conteúdo.

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

​

Iniciar a campanha

Quando você estiver pronto para iniciar sua campanha, basta retomar usando 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": "teste-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

As métricas para campanhas VIDEO_VIEWS_PREROLL estão disponíveis por meio de nossos endpoints de stats.

​

Segmentação por palavra-chave em timelines

A segmentação por palavra-chave é fundamental para nossos produtos de Promoted Tweets, ampliando o alcance das campanhas. A segmentação por palavra-chave em timelines permite que as plataformas alcancem usuários do X com base nas palavras‑chave presentes em seus Tweets recentes. Por exemplo, se um anunciante estiver segmentando a combinação não ordenada de palavras‑chave “plan + trip” e um usuário publicar um Tweet: “I’m starting to plan my trip to Cabo, any suggestions?” enquanto a campanha estiver ativa, esse usuário poderá, pouco depois, ver o Promoted Tweet do anunciante.

​

Como funciona?

TL;DR: do ponto de vista da API, essa mudança é bem simples: agora você pode segmentar palavras-chave em Tweets Promovidos no Timeline. Basta definir o targeting_type como unordered_keywords ou phrase_keywords para line items.

​

Guia de Introdução Rápida

• Crie um novo line item com o placement definido para incluir ALL_ON_TWITTER ou TWITTER_TIMELINE. POST accounts/:account_id/line_items
• Crie os critérios de segmentação para esse line item recém-criado com BROAD_KEYWORD e defina os valores da(s) palavra(s)-chave. POST accounts/:account_id/targeting_criteria
• Você pode atualizar as palavras-chave com PUT accounts/:account_id/targeting_criteria
• Quando sua campanha estiver em execução, obtenha as métricas do seu line item para avaliar o desempenho. GET stats/accounts/:account_id

​

Referência da API

​

Contas

Executar no Postman

​

GET accounts

Recupere detalhes de algumas ou de todas as contas com anúncios habilitados às quais o usuário autenticado tem acesso.

Resource URL

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

Parameters

Name	Description
account_ids optional	Restrinja a resposta apenas às IDs de conta desejadas especificando uma lista de identificadores separados por vírgula. Type: string Example: 18ce54d4x5t
count optional	Especifica o número de registros a tentar recuperar por solicitação. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Especifica um cursor para obter a próxima página de resultados. Consulte Pagination para mais informações. Type: string Example: 8x7v00oow
q optional	Uma query opcional para restringir o recurso por name. Note: Realiza correspondência por prefixo sem diferenciação de maiúsculas e minúsculas. Type: string Min, Max length: 1, 255
sort_by optional	Ordena por um atributo compatível em ordem ascendente ou descendente. Consulte Sorting para mais informações. Type: string Example: created_at-asc
with_deleted optional	Inclui resultados excluídos na sua solicitação. Type: boolean Default: false Possible values: true, false
with_total_count optional	Inclui o atributo de resposta total_count. Note: Este parâmetro e cursor são mutuamente exclusivos. Note: Solicitações que incluem total_count terão limites de requisições menores, atualmente definidos em 200 por 15 minutos. Type: boolean Default: false Possible values: true, false

​

Exemplo de solicitação

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

Exemplo de resposta

       {
         "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 uma conta específica à qual o usuário autenticado tem acesso.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta aproveitada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, com exceção de GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
with_deleted optional	Inclui resultados excluídos na sua solicitação. 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

Observação: APENAS SANDBOX

Crie uma conta de anúncios no ambiente de sandbox.

URL do recurso

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

Parâmetros

Nenhum

Exemplo de solicitação

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

Exemplo de resposta

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

​

PUT accounts/:account_id

Atualiza o nome da conta e/ou o setor de atuação.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, com exceção de GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
name optional	O nome da conta. Type: string Example: API McTestface
industry_type optional	Setor ao qual a conta está associada. 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

Observação: SOMENTE SANDBOX

Exclui uma conta de anúncios no ambiente de sandbox.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, com exceção de GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t

Example Request

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

Example Response

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

​

Apps da conta

Executar no Postman ❯

​

GET account_apps

Recupera os detalhes de todos os apps móveis associados à conta de anúncios especificada.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto em GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
count optional	Especifica o número de registros a serem recuperados por solicitação. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Especifica um cursor para obter a próxima página de resultados. Consulte Pagination para mais informações. Type: string Example: 8x7v00oow
sort_by optional	Ordena por um atributo compatível em ordem ascendente ou descendente. Consulte Sorting para mais informações. Type: string Example: created_at-asc
with_deleted optional	Inclui resultados excluídos na solicitação. Type: boolean Default: false Possible values: true, false
with_total_count optional	Inclui o atributo de resposta total_count. Note: Este parâmetro e cursor são mutuamente exclusivos. Note: Solicitações que incluem total_count terão limites de requisições menores, atualmente definidos em 200 por 15 minutos. 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
          }
         ]
       }

​

Histórico da conta

Executar no Postman

​

GET accounts/:account_id/account_history

Recupere um resumo das alterações feitas no entity_id especificado na solicitação.

Observação: Este endpoint está atualmente em beta e requer allowlisting.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta alavancada. Type: string Example: 18ce54d4x5t
count optional	Especifica o número de registros a serem recuperados por solicitação. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Especifica um cursor para obter a próxima página de resultados. Consulte Pagination para mais informações. Type: string Example: 8x7v00oow
entity_type required	O tipo de entidade para o qual os dados serão recuperados. Type: enum Example: PROMOTED_TWEET Possible values: CAMPAIGN, LINE_ITEM, PROMOTED_TWEET, TARGETING_CRITERIA, PROMOTED_ACCOUNT
entity_id required	A entidade específica para a qual os dados serão recuperados. Type: string Example: 8u94t
start_time required	Restringe os dados ao horário de início especificado, em ISO 8601. Observação: Deve ser expresso em horas cheias (0 minutos e 0 segundos). Type: string Example: 2017-05-19T07:00:00Z
end_time required	Restringe os dados ao horário de término especificado, em ISO 8601. Observação: Deve ser expresso em horas cheias (0 minutos e 0 segundos). Type: string Example: 2017-05-26T07:00:00Z
user_id optional	Restringe a resposta a um usuário específico. 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"
        }
      ]
    }

​

Categorias de negócios para anunciantes

Executar no Postman

​

GET advertiser_business_categories

Solicite as categories de negócios de anunciante válidas para Grupos de Anúncios (line_items) a fim de descrever a marca de um anunciante aos publishers.

Observação: Essas categorias se aplicam apenas a line_items com o objetivo PREROLL_VIEWS e são diferentes de content_categories, usadas para critérios de segmentação.

Cada advertiser_business_categories representa um conjunto de IAB Categories. Ao criar um Grupo de Anúncios com o objetivo PREROLL_VIEWS, é necessário definir uma ou duas advertiser_business_categories para o Grupo de Anúncios. Isso pode ser feito definindo o valor do parâmetro de requisição categories no endpoint de line item para o conjunto de iab_categories correspondentes disponíveis por meio deste endpoint.

Mais detalhes podem ser encontrados no Guia do Objetivo de Preroll para Visualizações de Vídeo

URL do recurso

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

Parâmetros

Nenhum parâmetro de requisição

Exemplo de requisição

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

Exemplo de resposta

{
      "request": {
        "params": {}
      },
      "next_cursor": null,
      "data": [
        {
          "id": "1jl",
          "name": "Bens de Consumo Embalados",
          "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": "Saúde e Farmacêutica",
          "iab_categories": [
            "IAB7"
          ]
        },
        {
          "id": "1jn",
          "name": "Bebidas Alcoólicas",
          "iab_categories": [
            "IAB8-5",
            "IAB8-18"
          ]
        },
        {
          "id": "1jo",
          "name": "Alimentação",
          "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": "Serviços Financeiros",
          "iab_categories": [
            "IAB3",
            "IAB13",
            "IAB21"
          ]
        },
        {
          "id": "1jq",
          "name": "Varejo",
          "iab_categories": [
            "IAB18"
          ]
        },
        {
          "id": "1jr",
          "name": "Viagens",
          "iab_categories": [
            "IAB20"
          ]
        },
        {
          "id": "1js",
          "name": "Games",
          "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": "Telecomunicações",
          "iab_categories": [
            "IAB19-6",
            "IAB19-18"
          ]
        },
        {
          "id": "1jv",
          "name": "Automotivo",
          "iab_categories": [
            "IAB2"
          ]
        },
        {
          "id": "1jw",
          "name": "Mídia e Entretenimento",
          "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": "Política",
          "iab_categories": [
            "IAB11-4"
          ]
        },
        {
          "id": "1jy",
          "name": "Apostas",
          "iab_categories": [
            "IAB9-7"
          ]
        },
        {
          "id": "1jz",
          "name": "Relacionamentos",
          "iab_categories": [
            "IAB14-1"
          ]
        },
        {
          "id": "1k0",
          "name": "Sem Fins Lucrativos"
          "iab_categories": [
            "IAB11-1",
            "IAB11-2",
            "IAB11-3",
            "IAB11-5"
          ]
        }
      ]
    }

​

Estimativa de audiência

Executar no Postman

POST accounts/:account_id/audience_estimate

​

Determine o tamanho aproximado do público das suas campanhas.

Este endpoint aceita um array de objetos JSON contendo os parâmetros dos objetos de critérios de segmentação. Uma lista de parâmetros obrigatórios e opcionais de critérios de segmentação está disponível no endpoint POST accounts/:account_id/targeting_criteria. As solicitações devem ser HTTP POST, com corpo JSON e cabeçalho Content-Type: application/json.

Observação: É necessário especificar pelo menos um critério de segmentação primário; você pode consultar a lista de todos os critérios de segmentação primários em nossa página de segmentação de campanhas.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
targeting_criteria required	Um objeto JSON contendo todos os parâmetros dos objetos de critérios de segmentação. Uma lista de parâmetros obrigatórios e opcionais de critérios de segmentação está disponível no endpoint POST accounts/:account_id/targeting_criteria.
operator_type optional	Especifique a relação que o critério de segmentação deve ter. Por exemplo, para configurar segmentação negativa, use 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"
            }
        ]
    }

Exemplo de resposta

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

​

Acesso de Usuário Autenticado

Executar no Postman

​

GET accounts/:account_id/authenticated_user_access

Recupera as permissões do usuário atualmente autenticado (access_token) em relação à conta de anúncios especificada. Essas permissões correspondem às exibidas em ads.x.com.

Os valores possíveis incluem:

• ACCOUNT_ADMIN: Acesso total para modificar campanhas e visualizar estatísticas, incluindo a possibilidade de adicionar ou remover usuários e alterar configurações
• AD_MANAGER: Acesso total para modificar campanhas e visualizar estatísticas, mas não pode adicionar ou remover usuários nem alterar configurações
• CREATIVE_MANAGER: Acesso para modificar criativos e visualizar prévias, mas sem acesso para criar ou modificar campanhas
• CAMPAIGN_ANALYST: Acesso para visualizar campanhas e estatísticas, mas sem acesso para criar ou modificar campanhas
• ANALYST (“Organic Analyst” em ads.x.com): Acesso para visualizar análises orgânicas e insights de público, mas sem acesso para criar, modificar ou visualizar campanhas
• PARTNER_AUDIENCE_MANAGER: Acesso somente via API para visualizar e modificar audiências de parceiros de dados, mas sem acesso a campanhas, criativos ou outros tipos de audiência.

Além disso, a permissão TWEET_COMPOSER indica que o usuário autenticado pode criar Tweets nullcasted (ou “Promoted-only”) em nome do anunciante. Isso está disponível apenas para usuários com acesso ACCOUNT_ADMIN, AD_MANAGER ou CREATIVE_MANAGER.

Resource URL

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

Parameters

Nenhum

Example Request

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

Example Response

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

​

Regras de lance

Executar no Postman

​

GET bidding_rules

Recupere as regras de lance para algumas ou todas as moedas. A resposta indicará os lances mínimos e máximos de CPE (custo por engajamento).

Embora essas regras de lance raramente mudem, recomenda-se que seus sistemas atualizem esses endpoints pelo menos mensalmente.

Resource URL

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

Parameters

Name	Description
currency optional	O tipo de moeda para filtrar os resultados, identificado usando ISO-4217. É uma string de três letras, como “USD” ou “EUR”. Omita este parâmetro para recuperar todas as regras de lance. 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
    }

​

Campanhas

Executar no Postman

​

GET accounts/:account_id/campaigns

Recupere detalhes de algumas ou de todas as campanhas associadas à conta atual.

Resource URL

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

Parameters

Name	Description
account_id required	Identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
campaign_ids optional	Restrinja a resposta apenas às campanhas desejadas especificando uma lista de identificadores separados por vírgula. É possível fornecer até 200 IDs. Type: string Example: 8wku2
count optional	Especifica a quantidade de registros a tentar recuperar por solicitação distinta. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Especifica um cursor para obter a próxima página de resultados. Consulte Pagination para mais informações. Type: string Example: 8x7v00oow
funding_instrument_ids optional	Restrinja a resposta apenas às campanhas sob instrumentos de financiamento específicos, especificando uma lista de identificadores separados por vírgula. É possível fornecer até 200 IDs. Type: string Example: lygyi
q optional	Uma query opcional para filtrar o recurso por name. Type: string Min, Max length: 1, 255
sort_by optional	Ordena por um atributo compatível em ordem ascendente ou descendente. Consulte Sorting para mais informações. Type: string Example: created_at-asc
with_deleted optional	Inclua resultados excluídos na sua solicitação. Type: boolean Default: false Possible values: true, false
with_draft optional	Inclua resultados de campanhas em rascunho na sua solicitação. Type: boolean Default: false Possible values: true, false
with_total_count optional	Inclua o atributo de resposta total_count. Note: Este parâmetro e cursor são mutuamente exclusivos. Note: Solicitações que incluem total_count terão limites de requisições menores, atualmente definidos em 200 por 15 minutos. 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": "teste",
          "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

Recupere uma campanha específica associada à conta atual.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
campaign_id required	Uma referência à campanha com a qual você está operando na solicitação. Type: string Example: 8wku2
with_deleted optional	Inclui resultados excluídos na solicitação. 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": "CAMPAIGN",
        "reasons_not_servable": [
          "PAUSED_BY_ADVERTISER",
          "INCOMPLETE"
        ],
        "servable": false,
        "purchase_order_number": null,
        "effective_status": "UNKNOWN",
        "daily_budget_amount_local_micro": 10000000,
        "funding_instrument_id": "lygyi",
        "duration_in_days": null,
        "standard_delivery": false,
        "total_budget_amount_local_micro": null,
        "id": "8wku2",
        "entity_status": "PAUSED",
        "frequency_cap": null,
        "currency": "USD",
        "created_at": "2022-06-03T21:38:07Z",
        "updated_at": "2022-06-03T21:38:07Z",
        "deleted": false
      }
    }

​

POST accounts/:account_id/campaigns

Crie uma nova campanha associada à conta atual.

Nota: Há um limite padrão de 200 campanhas ativas por conta. No entanto, não há limite para o número de campanhas inativas. Esse limite pode ser aumentado para 8.000 campanhas ativas. Para habilitar o limite maior, o anunciante deve solicitar ao seu X Account Manager.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
funding_instrument_id required	O identificador do instrumento de financiamento sob o qual a campanha será criada. Type: string Example: lygyi
name required	O nome da campanha. Comprimento máximo: 255 caracteres. Type: string Example: demo
budget_optimization optional	Selecione o tipo de otimização de orçamento a ser aplicada. Type: enum Default: CAMPAIGN Possible values: CAMPAIGN, LINE_ITEM
daily_budget_amount_local_micro sometimes required	O valor de orçamento diário a ser alocado para a campanha. A moeda associada ao instrumento de financiamento especificado será utilizada. Para USD, US$ 5,50 é representado como 5500000. Nota: Deve ser menor ou igual a total_budget_amount_local_micro e é obrigatório para a maioria dos tipos de instrumentos de financiamento. Type: long Example: 5500000
entity_status optional	O status da campanha. Type: enum Default: ACTIVE Possible values: ACTIVE, DRAFT, PAUSED
purchase_order_number optional	O número de referência da reserva. Use este campo para facilitar a conciliação de faturas. Comprimento máximo: 50 caracteres. Type: string Example: D00805843
standard_delivery optional	Habilite a veiculação padrão ou acelerada. Consulte Budget Pacing para mais informações sobre veiculação padrão versus acelerada. Disponível apenas quando budget_optimization estiver definido como CAMPAIGN. Type: boolean Default: true Possible values: true, false
total_budget_amount_local_micro optional	O valor total de orçamento a ser alocado para a campanha. A moeda associada ao instrumento de financiamento especificado será utilizada. Para USD, US$ 37,50 é representado como 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",
        "budget_optimization": "CAMPAIGN",
        "reasons_not_servable": [
          "PAUSED_BY_ADVERTISER",
          "INCOMPLETE"
        ],
        "servable": false,
        "purchase_order_number": null,
        "effective_status": "UNKNOWN",
        "daily_budget_amount_local_micro": 140000000,
        "funding_instrument_id": "lygyi",
        "duration_in_days": null,
        "standard_delivery": false,
        "total_budget_amount_local_micro": null,
        "id": "hwtbm",
        "entity_status": "PAUSED",
        "frequency_cap": null,
        "currency": "USD",
        "created_at": "2022-06-03T21:38:07Z",
        "updated_at": "2022-06-03T21:38:07Z",
        "deleted": false
      }
    }

​

POST batch/accounts/:account_id/campaigns

Permite criar novas campaigns em lote com uma única solicitação.

Solicitações em lote

• O tamanho máximo atual do lote é 40.
• Todos os parâmetros são enviados no corpo da solicitação e é obrigatório um Content-Type de application/json.
• As solicitações em lote falham ou são bem-sucedidas juntas, como um grupo, e todas as respostas da API — tanto de erro quanto de sucesso — preservam a ordem dos itens da solicitação inicial.

Respostas em lote

As respostas da API em lote retornam uma coleção ordenada de itens. Fora isso, são idênticas em estrutura aos endpoints correspondentes de item único.

Erros em lote

• Erros no nível da solicitação (por exemplo, tamanho máximo do lote excedido) são apresentados na resposta no objeto errors.
• Erros no nível do item (por exemplo, parâmetro obrigatório de campaign ausente) são apresentados na resposta no objeto operation_errors.

URL do recurso

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

Parâmetros

Name	Description
operation_type obrigatório	O tipo de operação por item que está sendo executado. Type: enum Possible values: Create, Delete, Update
params obrigatório	Um objeto JSON contendo todos os parâmetros dos objetos de campaign. Para a lista de parâmetros obrigatórios e opcionais de campaign, consulte aqui.

Exemplo de solicitação

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

    [
      {
        "operation_type":"Create",
        "params":{
          "name":"campanhas em lote",
          "funding_instrument_id":"lygyi",
          "daily_budget_amount_local_micro":140000000,
          "entity_status":"PAUSED",
          "budget_optimization":"CAMPAIGN"
        }
      }
    ]

Exemplo de resposta

    {
      "data": [
        {
          "name": "campanhas em lote",
          "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": "campanhas em lote",
            "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

Atualiza a campanha especificada associada à conta atual.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
campaign_id required	Uma referência à campanha com a qual você está operando na solicitação. Type: string Example: 8wku2
budget_optimization optional	Selecione o tipo de otimização de orçamento a ser aplicado. Type: enum Default: CAMPAIGN Possible values: CAMPAIGN, LINE_ITEM
daily_budget_amount_local_micro optional	O valor do orçamento diário a ser alocado para a campanha. A moeda associada ao instrumento de financiamento especificado será usada. Para USD, US$ 5,50 é representado como 5500000. Quando não fornecido, a campanha gastará de forma uniforme com base no orçamento total e durante o período de veiculação da campanha. Note: Isso deve ser menor ou igual a total_budget_amount_local_micro. Type: long Example: 5500000
entity_status optional	O status da campanha. Type: enum Possible values: ACTIVE, PAUSED
name optional	O nome da campanha. Comprimento máximo: 255 caracteres. Type: string Example: demo
purchase_order_number optional	O número de referência do pedido. Use este campo para auxiliar na conciliação de faturas. Comprimento máximo: 50 caracteres. Type: string Example: D00805843
standard_delivery optional	Ativa a veiculação padrão ou acelerada. Consulte Budget Pacing para mais informações sobre veiculação padrão versus acelerada. Disponível apenas quando budget_optimization está definido como CAMPAIGN. Type: boolean Default: true Possible values: true, false
total_budget_amount_local_micro optional	O valor total do orçamento a ser alocado para a campanha. A moeda associada ao instrumento de financiamento especificado será usada. Para USD, US$ 37,50 é representado como 37500000. Type: long Example: 140000000

Example Request

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

Example Response

    {
      "request": {
        "params": {
          "campaign_id": "8wku2",
          "daily_budget_amount_local_micro": 140000000,
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "name": "teste",
        "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

Exclui a campanha especificada pertencente à conta atual.

Observação: A exclusão de uma campanha é irreversível e tentativas subsequentes de excluir o recurso retornarão HTTP 404.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, com exceção de GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
campaign_id required	Referência à campanha com a qual você está operando na solicitação. Type: string Example: 8yn7m

Example Request

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

Example Response

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

​

Categorias de conteúdo

Executar no Postman

​

GET content_categories

Solicite as categories de conteúdo válidas a serem definidas como targeting_criteria para um item de linha.

Cada content_category corresponde a uma ou mais IAB Categories. Isso pode ser feito definindo o targeting_type como IAB_CATEGORY no endpoint em lote targeting_critera, para incluir o conjunto de iab_categories correspondentes retornado pela requisição content_categories. Caso contrário, ocorrerá um erro de validação.

Os detalhes de publisher para cada uma dessas categorias de conteúdo podem ser obtidos usando o endpoint GET publishers.

Mais detalhes podem ser encontrados no Guia do objetivo de pré‑roll de Visualizações de Vídeo.

URL do recurso

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

Parâmetros

Nenhum parâmetro de requisição

Exemplo de requisição

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

Exemplo de resposta

{
      "request": {
        "params": {}
      },
      "next_cursor": null,
      "data": [
        {
          "name": "Automotivo (Carros, Caminhões, Corridas)",
          "id": "ru",
          "iab_categories": [
            "IAB2"
          ],
          "publishers_in_last_thirty_days": 12,
          "videos_monetized_in_last_thirty_days": 316
        },
        {
          "name": "Comédia",
          "id": "sk",
          "iab_categories": [
            "IAB1-4"
          ],
          "publishers_in_last_thirty_days": 19,
          "videos_monetized_in_last_thirty_days": 174
        },
        {
          "name": "Criadores digitais",
          "id": "sl",
          "iab_categories": [
            "IAB25-1"
          ],
          "publishers_in_last_thirty_days": 110,
          "videos_monetized_in_last_thirty_days": 1257
        },
        {
          "name": "Entretenimento 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": "Notícias de finanças e negócios",
          "id": "sn",
          "iab_categories": [
            "IAB3",
            "IAB13",
            "IAB21"
          ],
          "publishers_in_last_thirty_days": 29,
          "videos_monetized_in_last_thirty_days": 1461
        },
        {
          "name": "Comida e bebida",
          "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": "Estilo de vida (Moda, Viagem, Bem-estar)",
          "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": "Música",
          "id": "sq",
          "iab_categories": [
            "IAB1-6"
          ],
          "publishers_in_last_thirty_days": 31,
          "videos_monetized_in_last_thirty_days": 518
        },
        {
          "name": "Notícias e atualidades",
          "id": "sr",
          "iab_categories": [
            "IAB12",
            "IAB14"
          ],
          "publishers_in_last_thirty_days": 125,
          "videos_monetized_in_last_thirty_days": 5507
        },
        {
          "name": "Política",
          "id": "s4",
          "iab_categories": [
            "IAB11"
          ],
          "publishers_in_last_thirty_days": 19,
          "videos_monetized_in_last_thirty_days": 1402
        },
        {
          "name": "Ciência e educação",
          "id": "ss",
          "iab_categories": [
            "IAB5",
            "IAB15"
          ],
          "publishers_in_last_thirty_days": 7,
          "videos_monetized_in_last_thirty_days": 132
        },
        {
          "name": "Esportes",
          "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": "Televisão",
          "id": "sh",
          "iab_categories": [
            "IAB1-7"
          ],
          "publishers_in_last_thirty_days": 58,
          "videos_monetized_in_last_thirty_days": 1307
        },
        {
          "name": "Esports e jogos eletrônicos",
          "id": "s0",
          "iab_categories": [
            "IAB9-30"
          ],
          "publishers_in_last_thirty_days": 109,
          "videos_monetized_in_last_thirty_days": 1844
        }
      ],
      "total_count": 15
    }

​

Categorias curadas

Executar no Postman

​

GET accounts/:account_id/curated_categories

Recupere uma lista de Curated Categories disponíveis para os country_codes informados

Cada curated_category está disponível apenas em países específicos indicados pelos country_codes na resposta.

Mais detalhes estão no Guia do objetivo Video Views Pre-roll.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
country_codes required	Restrinja a resposta apenas aos países desejados especificando uma lista, separada por vírgulas, de códigos de país ISO de duas letras. Até 200 IDs podem ser fornecidos. Type: string Example: US
cursor optional	Especifica um cursor para obter a próxima página de resultados. Consulte Pagination para mais informações. 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": "Basquete",
          "description": "Veicule ao lado do melhor conteúdo diário de basquete, incluindo equipes universitárias, equipes profissionais e os principais perfis de mídia esportiva que compartilham vídeos de basquete durante e fora da temporada.",
          "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": "Personalidades de games",
          "description": "Veicule ao lado do melhor conteúdo diário de games, exclusivamente de uma lista com alguns dos maiores e mais queridos criadores digitais de games online.",
          "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": "Beisebol",
          "description": "Veicule ao lado do melhor conteúdo diário de beisebol, incluindo equipes universitárias, equipes profissionais e os principais perfis de mídia esportiva que compartilham a cobertura mais relevante de beisebol.",
          "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": "Times de esports",
          "description": "Veicule ao lado da programação das melhores equipes de esports do mundo, cobrindo tanto transmissões de eventos quanto outra programação complementar ao longo do ano.",
          "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": "Futebol americano ",
          "description": "Veicule ao lado do melhor conteúdo diário de futebol americano, incluindo equipes universitárias, equipes profissionais e os principais perfis de mídia esportiva que compartilham vídeos de futebol americano durante e fora da temporada.",
          "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 + estilo de vida (masculino)"
          "description": "Exiba ao lado de conteúdo de um conjunto de contas selecionadas com base no perfil dos seguidores para ajudar você a alcançar um público majoritariamente masculino, incluindo algumas das principais contas que compartilham conteúdo de tecnologia, notícias e estilo de vida."
          "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 + estilo de vida (feminino)"
          "description": "Exiba ao lado de conteúdo de um conjunto de contas selecionadas com base no perfil dos seguidores para ajudar você a alcançar um público majoritariamente feminino, incluindo algumas das principais contas que compartilham conteúdo de cultura pop, notícias e estilo de vida."
          "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": "Leve e bem-humorado"
          "description": "Exiba ao lado de uma lista de contas selecionadas pelo volume de conteúdo positivo e reconfortante e pelas conversas que geram de forma consistente no 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": "Futebol (soccer)"
          "description": "Exiba ao lado do melhor conteúdo diário sobre futebol (soccer), incluindo equipes universitárias, equipes profissionais e as principais contas de mídia esportiva que compartilham cobertura relevante do esporte."
          "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

Recupere detalhes de um curated_category_id específico

Cada curated_category está disponível apenas em países específicos indicados por country_codes na resposta.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta em uso. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
curated_category_id required	Uma referência à Curated Category com a qual você está operando na solicitação. 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": "Futebol",
        "description": "Exiba anúncios ao lado do melhor conteúdo diário de futebol, incluindo equipes universitárias, equipes profissionais e os principais veículos de mídia esportiva que oferecem ampla cobertura do esporte.",
        "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
      }
    }

​

Funcionalidades

Executar no Postman

​

GET accounts/:account_id/features

Recupere a coleção de recursos concedidos acessíveis por esta conta de anúncios. Os recursos são identificados por uma chave descritiva e só são expostos neste endpoint se forem introduzidos em beta ou em outro tipo de lançamento limitado e estiverem disponíveis na X Ads API. Recursos que não atendem a esses critérios não serão expostos neste endpoint.

Observação: Este endpoint auxilia o desenvolvimento do ecossistema da X Ads API ao melhorar a visibilidade do acesso dos clientes a versões beta. Desenvolvedores da API não podem solicitar acesso a recursos em nome de um anunciante. Essas solicitações só podem ser feitas pelo anunciante ao seu gerente de conta na X.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
feature_keys optional	Parâmetro opcional que permite consultar uma chave de recurso específica. As solicitações podem incluir várias chaves separadas por vírgula. Observação: Somente os recursos acessíveis por esta conta serão incluídos na resposta. 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": [
        "SEGMENTAÇÃO_POR_CIDADE",
        "CARD_DE_CONVERSA",
        "ENQUETES_EM_MÍDIA_PROMOVIDA",
        "ANÁLISES_DE_ALCANCE_E_FREQUÊNCIA",
        "LIMITE_DE_FREQUÊNCIA_DE_ALCANCE",
        "PÚBLICO_SEMELHANTE_UNIVERSAL"
      ]
    }

​

POST accounts/:account_id/features

SOMENTE SANDBOX

Adiciona um recurso a uma conta de sandbox.

A lista atualizada de recursos da conta pode ser obtida por meio do 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	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: gq180y
feature_keys required	Uma lista, separada por vírgulas, de recursos da conta a serem adicionados à conta. 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

APENAS SANDBOX

Remove um recurso de uma conta sandbox.

A lista atualizada de recursos da conta pode ser obtida por meio do endpoint GET accounts/:account_id/features.

URL do recurso

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

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Tipo: string Exemplo: gq180y
feature_keys obrigatório	Uma lista, separada por vírgulas, de recursos da conta a serem removidos da conta. Tipo: enum Valores possíveis: 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

Exemplo de solicitação

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

Exemplo de resposta

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

​

Instrumentos de Financiamento

Executar no Postman

​

GET accounts/:account_id/funding_instruments

Recupere detalhes de alguns ou de todos os instrumentos de financiamento associados à conta atual.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta alavancada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, com exceção de GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
count optional	Especifica o número de registros a serem recuperados por solicitação. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Especifica um cursor para obter a próxima página de resultados. Consulte Pagination para mais informações. Type: string Example: 8x7v00oow
funding_instrument_ids optional	Restringe a resposta apenas aos instrumentos de financiamento desejados, especificando uma lista de identificadores separados por vírgula. Até 200 IDs podem ser fornecidos. Type: string Example: lygyi
sort_by optional	Ordena por um atributo compatível em ordem ascendente ou descendente. Consulte Sorting para mais informações. Type: string Example: created_at-asc
with_deleted optional	Inclui resultados excluídos na sua solicitação. Type: boolean Default: false Possible values: true, false
with_total_count optional	Inclui o atributo de resposta total_count. Note: Este parâmetro e cursor são mutuamente exclusivos. Note: Solicitações que incluem total_count terão limites de requisições menores, atualmente definidos em 200 por 15 minutos. 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 com final 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 um instrumento de financiamento específico associado à conta atual.

URL do recurso

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

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, com exceção de GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
funding_instrument_id obrigatório	Referência ao instrumento de financiamento utilizado na solicitação. Type: string Example: lygyi
with_deleted opcional	Inclui itens excluídos na resposta. Type: boolean Default: false Possible values: true, false

Exemplo de solicitação

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

Exemplo de resposta

    {
      "request": {
        "params": {
          "funding_instrument_id": "lygyi",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "start_time": "2016-07-22T04:24:04Z",
        "description": "Visa com final 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

APENAS SANDBOX

Crie um instrumento de financiamento no ambiente de sandbox.

Não há risco de incorrer em custos ao usar um instrumento de financiamento no sandbox.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: gq1844
currency required	A moeda, expressa em ISO-4217. Type: string Example: USD
start_time required	A data em que o instrumento de financiamento se tornará ativo e utilizável, expressa em ISO 8601. Type: string Example: 2017-05-19T07:00:00Z
type required	O tipo de instrumento de financiamento a ser criado. Type: enum Possible values: AGENCY_CREDIT_LINE, CREDIT_CARD, CREDIT_LINE, INSERTION_ORDER, PARTNER_MANAGED
end_time sometimes required	A data em que o instrumento de financiamento se tornará inativo, expressa em ISO 8601. Type: string Example: 2017-05-26T07:00:00Z
credit_limit_local_micro optional	O crédito total disponível para este instrumento de financiamento. Note: Aplicável somente a alguns tipos de instrumentos de financiamento. Type: long Example: 37500000
funded_amount_local_micro optional	O valor total de orçamento alocado a este instrumento de financiamento. Note: Aplicável somente a alguns tipos de instrumentos de financiamento. Type: long Example: 37500000

Example Request

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

Example Response

    {
      "data": {
        "start_time": "2017-07-10T00:00:00Z",
        "description": "(nenhum método de pagamento foi configurado ainda)",
        "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

APENAS SANDBOX

Exclui um instrumento de financiamento no ambiente de sandbox.

URL do recurso

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

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Tipo: string Exemplo: gq1844
funding_instrument_id obrigatório	Uma referência ao instrumento de financiamento com o qual você está operando na solicitação. Tipo: string Exemplo: hxt82

Exemplo de solicitação

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

Exemplo de resposta

    {
      "data": {
        "start_time": "2017-08-30T19:23:47Z",
        "description": "(nenhum método de pagamento foi configurado ainda)",
        "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"
        }
      }
    }

​

Categorias IAB

Executar no Postman

​

GET iab_categories

Solicite as categories de App válidas para grupos de anúncios (line_items).

URL do recurso

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

Parâmetros

Nome	Descrição
count opcional	Especifica o número de registros a tentar recuperar por solicitação distinta. Type: int Default: 200 Min, Max: 1, 1000
cursor opcional	Especifica um cursor para obter a próxima página de categorias. Consulte Pagination para mais informações. Type: string Example: gc-ddf4a
with_total_count opcional	Inclui o atributo de resposta total_count. Note: Este parâmetro e cursor são excludentes. Note: Solicitações que incluem total_count terão limites de requisições menores, atualmente definidos em 200 por 15 minutos. Type: boolean Default: false Possible values: true, false

Exemplo de solicitação

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

Exemplo de resposta

    {
      "data": [
        {
          "id": "IAB1",
          "parent_id": null,
          "name": "Artes e Entretenimento"
        },
        {
          "id": "IAB1-1",
          "parent_id": "IAB1",
          "name": "Livros e Literatura"
        }
      ],
      "next_cursor": "uxa8",
      "request": {
        "params": {
          "count": 2
        }
      }
    }

​

Itens de linha

Executar no Postman

​

GET accounts/:account_id/line_items

Recupere detalhes de alguns ou de todos os line items associados à conta atual.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, com exceção de GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
campaign_ids optional	Restrinja a resposta apenas aos line items de campanhas específicas informando uma lista de identificadores separados por vírgula. É possível fornecer até 200 IDs. Type: string Example: 8gdx6
count optional	Especifica o número de registros a tentar recuperar por solicitação. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Especifica um cursor para obter a próxima página de resultados. Consulte Pagination para mais informações. Type: string Example: 8x7v00oow
funding_instrument_ids optional	Restrinja a resposta apenas aos line items de instrumentos de financiamento específicos informando uma lista de identificadores separados por vírgula. É possível fornecer até 200 IDs. Type: string Example: lygyi
line_item_ids optional	Restrinja a resposta apenas aos line items desejados informando uma lista de identificadores separados por vírgula. É possível fornecer até 200 IDs. Type: string Example: 8v7jo
q optional	Uma query opcional para filtrar o recurso por name. Type: string Min, Max length: 1, 255
sort_by optional	Ordena por um atributo compatível em ordem crescente ou decrescente. Consulte Sorting para mais informações. Type: string Example: created_at-asc
with_deleted optional	Inclui resultados excluídos na sua solicitação. Type: boolean Default: false Possible values: true, false
with_draft optional	Inclui resultados de campanhas em rascunho na sua solicitação. Type: boolean Default: false Possible values: true, false
with_total_count optional	Inclui o atributo de resposta total_count. Note: Este parâmetro e cursor são mutuamente exclusivos. Note: Solicitações que incluem total_count terão limites de requisições menores, atualmente definidos em 200 por 15 minutos. 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 um item de linha específico associado à conta atual.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta usada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto em GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
line_item_id required	Referência ao item de linha com o qual você está operando na solicitação. Type: string Example: 8v7jo
with_deleted optional	Inclui resultados excluídos na solicitação. Type: boolean Default: false Possible values: true, false

Example Request

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

Example Response

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

Cria um item de linha associado à campanha especificada pertencente à conta atual.

Todos os itens de linha em uma campanha devem ter o mesmo product_type e objective.

Ao usar o tipo de produto PROMOTED_ACCOUNT, associar um Tweet ao line_item adicionará posicionamentos na linha do tempo em dispositivos móveis, além do posicionamento padrão de PROMOTED_ACCOUNT.

Definir android_app_store_identifier ou ios_app_store_identifier adicionará automaticamente os critérios de segmentação do item de linha correspondentes ao app móvel que está sendo promovido; por exemplo, enviar ios_app_store_identifier adicionará o critério de segmentação PLATFORM targeting criteria para iOS.

Observação: há um limite de 100 itens de linha por campanha e 256 itens de linha ativos em todas as campanhas.

Resource URL

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

Parameters

Nome	Descrição
account_id obrigatório	O identificador da conta alavancada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da API do Anunciante, excluindo GET accounts. A conta especificada deve estar associada ao usuário autenticado. Tipo: string Exemplo: 18ce54d4x5t
campaign_id obrigatório	O identificador da campanha sob a qual criar o item de linha. Tipo: string Exemplo: 8slvg
end_time obrigatório	O horário, expresso em ISO 8601, em que o item de linha parará de ser veiculado. Tipo: string Exemplo: 2017-10-05T00:00:00Z
objective obrigatório	O objetivo da campanha para este item de linha. Tipo: enum Valores possíveis: APP_ENGAGEMENTS, APP_INSTALLS, REACH, FOLLOWERS, ENGAGEMENTS, VIDEO_VIEWS, PREROLL_VIEWS, WEBSITE_CLICKS
placements obrigatório	O(s) local(is) de veiculação para este item de linha ser exibido. Especifique uma lista separada por vírgulas de valores de veiculação. Tipo: enum Valores possíveis: 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 obrigatório	O tipo de produto promovido que este item de linha conterá. Tipo: enum Valores possíveis: MEDIA, PROMOTED_ACCOUNT, PROMOTED_TWEETS
start_time obrigatório	O horário, expresso em ISO 8601, em que o item de linha começará a ser veiculado. Tipo: string Exemplo: 2017-07-05T00:00:00Z
advertiser_domain às vezes obrigatório	O domínio do site para este anunciante, sem a especificação do protocolo. Observação: Obrigatório quando a veiculação do item de linha está definida como PUBLISHER_NETWORK. Tipo: string Exemplo: x.com
android_app_store_identifier às vezes obrigatório	O identificador da Google Play Store para aplicativos promovidos. Observação: Os objetivos APP_INSTALLS e APP_ENGAGEMENTS requerem definir pelo menos um identificador de loja de aplicativos — seja android_app_store_identifier ou ios_app_store_identifier. Tipo: string Exemplo: com.twitter.android
bid_amount_local_micro às vezes obrigatório	O valor do lance a ser associado a este item de linha. A moeda associada ao instrumento de financiamento especificado será usada. Para USD, $5,50 é representado como 5500000. Observação: Obrigatório se bid_strategy estiver definido como MAX ou TARGET Observação: Apenas valores maiores que zero são aceitos. Tipo: long Exemplo: 5500000
categories às vezes obrigatório	As categorias IAB relevantes para este anunciante. Consulte GET iab_categories. Observação: Obrigatório quando a veiculação do item de linha está definida como PUBLISHER_NETWORK. Tipo: string Exemplo: IAB3-1
ios_app_store_identifier às vezes obrigatório	A parte numérica do identificador da Apple App Store para aplicativos promovidos. Observação: Os objetivos APP_INSTALLS e APP_ENGAGEMENTS requerem definir pelo menos um identificador de loja de aplicativos — seja android_app_store_identifier ou ios_app_store_identifier. Tipo: string Exemplo: 333903271
primary_web_event_tag às vezes obrigatório	O identificador da tag de evento web primária. Permite rastreamento mais preciso de engajamentos para a campanha relacionada a este item de linha. Observação: Obrigatório quando o objetivo do item de linha está definido como WEBSITE_CONVERSIONS. Tipo: string Exemplo: nvo4z
advertiser_user_id opcional	O identificador de usuário do X para o perfil que promove um anúncio PREROLL_VIEWS. Apenas certas aplicações cliente podem usar este parâmetro. Tipo: string Exemplo: 312226591
audience_expansion opcional	Usado para expandir o alcance das campanhas segmentando usuários similares àqueles já segmentados. Observação: Por padrão, nenhuma expansão será aplicada. Tipo: enum Valores possíveis: BROAD, DEFINED, EXPANDED
bid_strategy opcional	O mecanismo de lances. AUTO otimiza automaticamente os lances com base no orçamento diário e nas datas de execução da campanha. MAX define o lance máximo permitido e não está disponível quando o objetivo está definido como REACH ou FOLLOWERS. TARGET tenta fazer com que as médias diárias de lances fiquem dentro de 20% do bid_amount_local_micro especificado e está disponível quando o objetivo está definido como REACH, FOLLOWERS OU WEBSITE_CLICKS. Observação: Se definido como AUTO, bid_amount_local_micro será ignorado. Observação: Padrão baseado no objetivo. Tipo: enum Valores possíveis: AUTO, MAX, TARGET
duration_in_days opcional	O período de tempo dentro do qual o frequency_cap é alcançado. Tipo: int Valores possíveis: 1, 7, 30
entity_status opcional	O status do item de linha. Tipo: enum Padrão: ACTIVE Valores possíveis: ACTIVE, DRAFT, PAUSED
frequency_cap opcional	O número máximo de vezes que um anúncio pode ser entregue a um usuário. Observação: Suportado apenas para os objetivos REACH, ENGAGEMENTS, VIDEO_VIEWS e PREROLL_VIEWS. Tipo: int Exemplo: 5
goal opcional	A configuração de otimização a ser usada com este item de linha. A opção APP_PURCHASES está disponível para APP_INSTALL. As opções APP_CLICKS e APP_INSTALLS estão disponíveis para os objetivos APP_INSTALL e APP_ENGAGEMENTS e podem exigir o uso de um parceiro MACT suportado. A opção SITE_VISITS está disponível apenas com o objetivo WEBSITE_CLICKS. Observação: Padrão baseado no objetivo. Tipo: enum Valores possíveis: 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 opcional	O nome para o item de linha. Tipo: string Exemplo: demo Comprimento mín., máx.: 1, 255
pay_by opcional	A unidade de cobrança para este item de linha. Esta configuração só pode ser modificada para itens de linha que usam o objetivo APP_INSTALLS. Observação: O pay_by padrão é definido automaticamente com base no objetivo da campanha e na unidade de lance do item de linha. O objetivo APP_INSTALLS oferece suporte aos valores APP_CLICK e IMPRESSION. IMPRESSION é o valor padrão. O objetivo LINK_CLICKS oferece suporte aos valores LINK_CLICK e IMPRESSION. IMPRESSION é o valor padrão, mas não é compatível ao definir TARGET para bid_strategy. O objetivo SITE_VISITS oferece suporte aos valores IMPRESSION. Tipo: enum Valores possíveis: APP_CLICK, IMPRESSION, LINK_CLICK
standard_delivery opcional	Habilita entrega padrão ou acelerada. Consulte Ritmo de Orçamento para mais informações sobre entrega padrão versus acelerada. Disponível apenas quando budget_optimization está definido como LINE_ITEM para a campanha principal Tipo: boolean Padrão: true Valores possíveis: true, false
total_budget_amount_local_micro opcional	O valor total do orçamento a ser alocado ao item de linha. Será usada a moeda associada ao instrumento de financiamento especificado. Para USD, $37,50 é representado como 37500000. Tipo: long Exemplo: 37500000
daily_budget_amount_local_micro às vezes obrigatório	O valor do orçamento diário a ser alocado à campanha. Será usada a moeda associada ao instrumento de financiamento especificado. Para USD, $5,50 é representado como 5500000. Quando não fornecido, a campanha gastará de forma uniforme com base no orçamento total e na duração do período de veiculação da campanha. Disponível apenas quando budget_optimization está definido como LINE_ITEM para a campanha principal Observação: Este valor deve ser menor ou igual ao total_budget_amount_local_micro. Tipo: long Exemplo: 5500000

Exemplo de requisição

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

Exemplo de resposta

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

Permite criar em lote novos line items com uma única solicitação.

Solicitações em lote

• O tamanho máximo atual do lote é 40.
• Todos os parâmetros são enviados no corpo da solicitação e é necessário Content-Type: application/json.
• Solicitações em lote falham ou são bem-sucedidas juntas, como um grupo, e todas as respostas da API — de erro ou sucesso — preservam a ordem dos itens da solicitação inicial.

Respostas em lote

As respostas da API em lote retornam uma coleção ordenada de itens. Fora isso, são idênticas em estrutura aos endpoints correspondentes de item único.

Erros em lote

• Erros no nível da solicitação (por exemplo, tamanho máximo do lote excedido) são exibidos na resposta em errors.
• Erros no nível do item (por exemplo, parâmetro obrigatório do line item ausente) são exibidos na resposta em operation_errors.

URL do recurso

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

Parâmetros

Nome	Descrição
operation_type obrigatório	O tipo de operação por item que está sendo executada. Type: enum Valores possíveis: Create, Delete, Update
params obrigatório	Um objeto JSON contendo todos os parâmetros dos objetos de line item. Para a lista de parâmetros obrigatórios e opcionais de line item, consulte aqui.

Exemplo de solicitação

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

Exemplo de resposta

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

Atualize o item de linha especificado associado à conta atual.

URL do recurso

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

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta alavancada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da API do Anunciante, excluindo GET accounts. A conta especificada deve estar associada ao usuário autenticado. Tipo: string Exemplo: 18ce54d4x5t
line_item_id obrigatório	Uma referência ao item de linha com o qual você está operando na solicitação. Tipo: string Exemplo: 8v7jo
advertiser_domain opcional	O domínio do site para este anunciante, sem a especificação do protocolo. Observação: Obrigatório quando o posicionamento do item de linha está definido como PUBLISHER_NETWORK. Tipo: string Exemplo: x.com
advertiser_user_id opcional	O identificador de usuário do X para o handle que promove um anúncio PREROLL_VIEWS. Apenas certas aplicações cliente podem usar este parâmetro. Tipo: string Exemplo: 312226591
android_app_store_identifier opcional	O identificador da Google Play Store para a aplicação promovida. Observação: Os objetivos APP_INSTALLS e APP_ENGAGEMENTS requerem definir pelo menos um identificador de loja de aplicativos — seja android_app_store_identifier ou ios_app_store_identifier. Tipo: string Exemplo: com.twitter.android
audience_expansion opcional	Usado para expandir o alcance das campanhas segmentando usuários similares àqueles já segmentados. Tipo: enum Valores possíveis: BROAD, DEFINED, EXPANDED
bid_amount_local_micro opcional	O valor do lance a ser associado a este item de linha. A moeda associada ao instrumento de financiamento especificado será usada. Para USD, $5,50 é representado como 5500000. Observação: Obrigatório se bid_strategy estiver definido como MAX ou TARGET Observação: Apenas valores maiores que zero são aceitos. Tipo: long Exemplo: 140000
bid_strategy opcional	O mecanismo de lances. AUTO otimiza automaticamente os lances com base no orçamento diário e nas datas de veiculação da campanha. MAX define o lance máximo permitido e não está disponível quando o objetivo está definido como REACH ou FOLLOWERS. TARGET tenta fazer com que as médias diárias de lances fiquem dentro de 20% do bid_amount_local_micro especificado e está disponível quando o objetivo está definido como REACH ou WEBSITE_CLICKS. Observação: Se definido como AUTO, bid_amount_local_micro será ignorado. Observação: Padrão baseado no objetivo. Tipo: enum Valores possíveis: AUTO, MAX, TARGET
categories opcional	As categorias IAB relevantes para este anunciante. Consulte GET iab_categories. Observação: Obrigatório quando o posicionamento do item de linha está definido como PUBLISHER_NETWORK. Tipo: string Exemplo: IAB3-1
duration_in_days opcional	O período de tempo dentro do qual o frequency_cap é atingido. Tipo: int Valores possíveis: 1, 7, 30
entity_status opcional	O status do item de linha. Tipo: enum Valores possíveis: ACTIVE, PAUSED
end_time opcional	O horário, expresso em ISO 8601, em que o item de linha parará de ser veiculado. Tipo: string Exemplo: 2017-10-05T00:00:00Z
frequency_cap opcional	O número máximo de vezes que um anúncio pode ser entregue a um usuário. Observação: Suportado apenas para os objetivos REACH, ENGAGEMENTS, VIDEO_VIEWS e PREROLL_VIEWS. Tipo: int Exemplo: 5
goal opcional	A configuração de otimização a ser usada com este item de linha. A opção APP_PURCHASES está disponível para APP_INSTALL. As opções APP_CLICKS e APP_INSTALLS estão disponíveis para APP_INSTALL e APP_ENGAGEMENTS e podem exigir o uso de um parceiro MACT suportado. Observação: Padrão baseado no objetivo. Tipo: enum Valores possíveis: 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 opcional	A parte numérica do identificador da Apple App Store para aplicações promovidas. Observação: Os objetivos APP_INSTALLS e APP_ENGAGEMENTS requerem definir pelo menos um identificador de loja de aplicativos — seja android_app_store_identifier ou ios_app_store_identifier. Tipo: string Exemplo: 333903271
name opcional	O nome para o item de linha. Tipo: string Exemplo: demo
pay_by opcional	A unidade pela qual cobrar este item de linha. Esta configuração só pode ser modificada para itens de linha usando o objetivo APP_INSTALLS. Observação: O pay_by padrão é automaticamente definido com base no objetivo da campanha e na unidade de lance do item de linha. O objetivo APP_INSTALLS suporta os valores APP_CLICK e IMPRESSION. IMPRESSION é o valor padrão. O objetivo LINK_CLICKS suporta os valores LINK_CLICK e IMPRESSION. IMPRESSION é o valor padrão, mas não é suportado ao definir TARGET para bid_strategy. O objetivo SITE_VISITS suporta valores IMPRESSION. Tipo: enum Valores possíveis: APP_CLICK, IMPRESSION, LINK_CLICK
start_time opcional	O horário, expresso em ISO 8601, em que o item de linha começará a ser veiculado. Tipo: string Exemplo: 2017-07-05T00:00:00Z
total_budget_amount_local_micro opcional	O valor total do orçamento a ser alocado ao item de linha. A moeda associada ao instrumento de financiamento especificado será usada. Para USD, $37,50 é representado como 37500000. Tipo: long Exemplo: 37500000
daily_budget_amount_local_micro opcional	O valor do orçamento diário a ser alocado à campanha. A moeda associada ao instrumento de financiamento especificado será usada. Para USD, $5,50 é representado como 5500000. Quando não fornecido, a campanha gastará uniformemente com base no orçamento total e na duração do período de veiculação da campanha. Disponível apenas quando budget_optimization está definido como LINE_ITEM para a campanha pai Observação: Este deve ser menor ou igual ao total_budget_amount_local_micro. Tipo: long Exemplo: 5500000

Exemplo de requisição

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

Exemplo de resposta

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

Exclui o item de linha especificado pertencente à conta atual.

Observação: A exclusão de um item de linha é irreversível e tentativas subsequentes de excluir o recurso retornarão HTTP 404.

Observação: Quando um item de linha é excluído, seus promoted_tweets filhos só são retornados nos endpoints GET accounts/:account_id/promoted_tweets e GET accounts/:account_id/promoted_tweets/:promoted_tweet_id se with_deleted=true for especificado na solicitação. Esses promoted_tweets não são realmente excluídos ("deleted": false na resposta). Não executamos exclusões em cascata.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, com exceção de GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
line_item_id required	A referência ao item de linha com o qual você está operando na solicitação. 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": "Sem título",
        "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"
        }
      }
    }

​

Categorias curadas de Itens de Linha

Executar no Postman

Mais detalhes sobre o uso podem ser encontrados no Guia do Objetivo de Visualizações de Vídeo (pré‑roll)

​

GET accounts/:account_id/line_item_curated_categories

Recupera detalhes de algumas ou de todas as categorias curadas de itens de linha associadas à conta atual.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
count optional	Especifica o número de registros a tentar recuperar por solicitação. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Especifica um cursor para obter a próxima página de resultados. Consulte Pagination para mais informações. Type: string Example: 8x7v00oow
sort_by optional	Ordena por um atributo compatível em ordem crescente ou decrescente. Consulte Sorting para mais informações. Type: string Example: created_at-asc
with_deleted optional	Inclui resultados excluídos na sua solicitação. Type: boolean Default: false Possible values: true, false
with_total_count optional	Inclui o atributo de resposta total_count. Note: Este parâmetro e cursor são mutuamente exclusivos. Note: Solicitações que incluem total_count têm limites de requisições menores, atualmente definidos em 200 por 15 minutos. 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 os detalhes de uma categoria curada de item de linha específica associada à conta atual.

URL do recurso

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

Parâmetros

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, com exceção de GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
line_item_curated_category_id required	Referência à categoria curada de item de linha com a qual você está operando na solicitação. Type: string Example: 43853bhii885
with_deleted optional	Incluir resultados excluídos na solicitação. Type: boolean Default: false Possible values: true, false

Exemplo de solicitação

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

Exemplo de resposta

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

​

POST accounts/:account_id/line_item_curated_categories

Associe um objeto de curated category ao line item especificado.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
curated_category_id required	Uma referência à entidade curated category com a qual você está operando na solicitação. Type: string Example: 10miy
line_item_id required	Uma referência ao line item com o qual você está operando na solicitação. 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

Atualiza a categoria curada do item de linha especificado.

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	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, com exceção de GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
line_item_curated_category_id required	Uma referência à categoria curada do item de linha com a qual você está operando na solicitação. Type: string Example: 1bzq3
curated_category_id optional	Uma referência à entidade de categoria curada com a qual você está operando na solicitação. Type: string Example: 10miy
line_item_id optional	Uma referência ao item de linha com o qual você está operando na solicitação. Type: string Example: 8v7jo

Example Request

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

Example Response

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

​

DELETE accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id

Exclui a categoria curada do item de linha especificada.

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	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
line_item_curated_category_id required	Uma referência à categoria curada do item de linha com a qual você está operando na solicitação. Type: string Example: 1bzq3

Example Request

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

Example Response

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

​

Posicionamentos de line item

Executar no Postman

​

GET line_items/placements

Recupere combinações válidas de placement e product_type.

Resource URL

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

Parameters

Nome	Descrição
product_type opcional	Restrinja a resposta apenas aos placements válidos para o tipo de produto especificado. Type: enum Possible values: MEDIA, PROMOTED_ACCOUNT, PROMOTED_TWEETS

Example Request

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

Example Response

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

​

Criativos de mídia

Executar no Postman

​

GET accounts/:account_id/media_creatives

Recupere detalhes de alguns ou de todos os media creatives associados à conta atual.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto em GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
campaign_id optional	Restringe a resposta apenas aos media creatives associados à campanha especificada. Type: string Example: 8gdx6
count optional	Especifica a quantidade de registros a tentar recuperar por solicitação. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Especifica um cursor para obter a próxima página de resultados. Consulte Pagination para mais informações. Type: string Example: 8x7v00oow
line_item_ids optional	Restringe a resposta apenas aos media creatives associados aos line items especificados, informando uma lista de identificadores separados por vírgula. Até 200 IDs podem ser fornecidos. Type: string Example: 8v7jo
media_creative_ids optional	Restringe a resposta apenas aos media creatives desejados, informando uma lista de identificadores separados por vírgula. Até 200 IDs podem ser fornecidos. Type: string Example: 1bzq3
sort_by optional	Ordena por um atributo compatível em ordem ascendente ou descendente. Consulte Sorting para mais informações. Type: string Example: created_at-asc
with_deleted optional	Inclui resultados excluídos na solicitação. Type: boolean Default: false Possible values: true, false
with_total_count optional	Inclui o atributo de resposta total_count. Nota: Este parâmetro e cursor são mutuamente exclusivos. Nota: Solicitações que incluem total_count terão limites de requisições menores, atualmente definidos em 200 por 15 minutos. 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 os detalhes de um criativo de mídia específico associado à conta atual.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto em GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
media_creative_id required	Uma referência ao criativo de mídia com o qual você está operando na solicitação. Type: string Example: 43853bhii885
with_deleted optional	Incluir resultados excluídos na solicitação. 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

Associe um objeto de account media ao line item especificado.

Use este endpoint para promover anúncios in-stream (quando o creative_type do account media é PREROLL) ou anúncios de imagem (como BANNER ou INTERSTITIAL) na Twitter Audience Platform.

Observação: Para adicionar recursos de mídia ao recurso Account Media, use o endpoint POST accounts/:account_id/media_library.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
account_media_id required	Uma referência ao entity de account media com a qual você está operando na solicitação. Type: string Example: 10miy
line_item_id required	Uma referência ao line item com o qual você está operando na solicitação. Type: string Example: 8v7jo
landing_url sometimes required	A URL do site para o qual o usuário será direcionado. Deve ser usada apenas com imagens TAP (ou “display creatives”). Esse valor será ignorado se usado com assets de preroll. Para associar uma URL a um asset de preroll, use o endpoint POST accounts/:account_id/preroll_call_to_actions. Observação: Obrigatória quando o objetivo do line item estiver definido como 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

Exclui o media creative especificado pertencente à conta atual.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
media_creative_id required	Uma referência ao media creative com o qual você está operando na solicitação. 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
      }
    }

​

Contas promovidas

Executar no Postman

​

GET accounts/:account_id/promoted_accounts

Recupere detalhes de algumas ou todas as contas promovidas associadas a um ou mais line items na conta atual.

Use GET users/lookup para obter dados dos usuários das contas identificadas por user_id na resposta.

Um HTTP 400 será retornado se nenhum dos line items especificados estiver configurado para conter contas promovidas.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
count optional	Especifica o número de registros a tentar recuperar por solicitação distinta. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Especifica um cursor para obter a próxima página de resultados. Consulte Pagination para mais informações. Type: string Example: 8x7v00oow
line_item_ids optional	Restrinja a resposta apenas às contas promovidas associadas aos line items especificados, informando uma lista de identificadores separados por vírgula. Até 200 IDs podem ser fornecidos. Type: string Example: 9bpb2
promoted_account_ids optional	Restrinja a resposta apenas às contas promovidas desejadas, informando uma lista de identificadores separados por vírgula. Até 200 IDs podem ser fornecidos. Type: string Example: 19pl2
sort_by optional	Classifica por atributo compatível em ordem ascendente ou descendente. Consulte Sorting para mais informações. Type: string Example: created_at-asc
with_deleted optional	Inclua resultados excluídos na sua solicitação. Type: boolean Default: false Possible values: true, false
with_total_count optional	Inclua o atributo de resposta total_count. Note: Este parâmetro e cursor são mutuamente exclusivos. Note: Solicitações que incluem total_count terão limites de requisições mais baixos, atualmente definidos em 200 por 15 minutos. 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 uma referência específica a uma conta associada a um line item na conta atual.

URL do recurso

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

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, com exceção de GET accounts. A conta especificada deve estar associada ao usuário autenticado. Tipo: string Exemplo: 18ce54d4x5t
promoted_account_id obrigatório	Uma referência à conta promovida com a qual você está operando na solicitação. Tipo: string Exemplo: 19pl2
with_deleted opcional	Inclui resultados excluídos na solicitação. Tipo: boolean Padrão: false Valores possíveis: true, false

Exemplo de solicitação

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

Exemplo de resposta

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

​

POST accounts/:account_id/promoted_accounts

Associe uma conta (user_id) ao item de linha especificado.

Se o item de linha especificado não estiver configurado para se associar a Promoted Accounts, será retornado um erro HTTP 400 INCOMPATIBLE_LINE_ITEM. Se o usuário especificado não for elegível para promoção, será retornado um HTTP 400 e nenhum usuário será promovido. Se o usuário informado já estiver promovido, a solicitação será ignorada.

Para mais informações sobre Promoted Accounts, consulte nossa página de campaign management.

Observação: Não é possível atualizar (PUT) entidades de Promoted Accounts.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
line_item_id required	Uma referência ao item de linha com o qual você está operando na solicitação. Type: string Example: 9bpb2
user_id required	Uma referência ao usuário com o qual você está operando na solicitação. Use GET users/lookup para recuperar um user ID a partir de um 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

Desassocia uma conta do item de linha especificado.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, com exceção de GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
promoted_account_id required	O identificador da instância de uma Promoted Account associada a um item de linha. Type: string Example: 19pl2

Example Request

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

Example Response

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

​

Tweets promovidos

Executar no Postman

​

GET accounts/:account_id/promoted_tweets

Recupere referências a Tweets associados a itens de linha na conta atual.

Use o endpoint GET accounts/:account_id/tweets para buscar os objetos Tweet. Use os valores de tweet_id para cada objeto de promoted_tweets.

Observação: Quando os itens de linha pai são excluídos, promoted_tweets só são retornados se with_deleted=true for especificado na solicitação. Esses promoted_tweets, porém, não são de fato excluídos ("deleted": false na resposta).

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, com exceção de GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
count optional	Especifica o número de registros a tentar recuperar por solicitação. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Especifica um cursor para obter a próxima página de resultados. Consulte Pagination para mais informações. Type: string Example: 8x7v00oow
line_item_ids optional	Restrinja a resposta apenas aos Tweets associados a itens de linha específicos, especificando uma lista de identificadores separados por vírgulas. Até 200 IDs podem ser fornecidos. Type: string Example: 96uzp
promoted_tweet_ids optional	Restrinja a resposta apenas aos Tweets promovidos desejados, especificando uma lista de identificadores separados por vírgulas. Até 200 IDs podem ser fornecidos. Type: string Example: 1efwlo
sort_by optional	Ordena por um atributo compatível em ordem crescente ou decrescente. Consulte Sorting para mais informações. Type: string Example: created_at-asc
with_deleted optional	Inclui resultados excluídos na solicitação. Type: boolean Default: false Possible values: true, false
with_total_count optional	Inclui o atributo de resposta total_count. Observação: Este parâmetro e cursor são mutuamente exclusivos. Observação: Solicitações que incluem total_count terão limites de requisições menores, atualmente definidos em 200 por 15 minutos. 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

Recupere uma referência específica a um Tweet associado a um item de linha na conta atual.

Observação: Quando os itens de linha pai são excluídos, promoted_tweets só são retornados se with_deleted=true for especificado na solicitação. Esses promoted_tweets não são realmente excluídos ("deleted": false na resposta).

Resource URL

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

Parameters

Name	Description
account_id obrigatório	O identificador da conta aproveitada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, com exceção de GET accounts. A conta especificada deve estar associada ao usuário autenticado. Tipo: string Exemplo: 18ce54d4x5t
promoted_tweet_id obrigatório	Uma referência ao Tweet promovido com o qual você está operando na solicitação. Tipo: string Exemplo: 1efwlo
with_deleted opcional	Inclua resultados excluídos na sua solicitação. Tipo: boolean Padrão: false Valores possíveis: true, false

Example Request

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

Example Response

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

​

POST accounts/:account_id/promoted_tweets

Associe um ou mais Tweets ao item de linha especificado. Nem todos os Tweets são apropriados para promoção, dependendo do objetivo da campanha. Consulte Objective-based Campaigns para mais informações.

Ao usar o produto PROMOTED_ACCOUNT, associar um Tweet ao line_item adicionará posicionamentos na timeline em dispositivos móveis, além do posicionamento padrão de PROMOTED_ACCOUNT.

Observação: Não é possível atualizar (PUT) entidades de Tweet promovido.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
line_item_id required	Uma referência ao item de linha com o qual você está operando na solicitação. Type: string Example: 8v7jo
tweet_ids required	Uma lista de ids separados por vírgulas correspondente a Tweets específicos. Podem ser fornecidos até 50 ids. 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

Desassocia um Tweet do line item especificado.

Observação: Uma entidade promoted_tweets excluída será exibida como “Paused” na interface do ads.x.com. Da mesma forma, realizar “pausing” pela interface desassociará o Tweet do seu line item.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta utilizada. Aparece no path do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, com exceção de GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
promoted_tweet_id required	O identificador que se refere à instância de um Promoted Tweet associada a um line item. Ele vem do campo id de um item de resposta de GET accounts/:account_id/promoted_tweets, não do tweet_id do Tweet em questão. Fornecido no path do recurso. Type: string Example: 1gp8a5

Example Request

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

Example Response

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

​

Usuários promovíveis

Executar no Postman

​

GET accounts/:account_id/promotable_users

Recupere detalhes de alguns ou de todos os usuários promovíveis associados à conta atual.

O tipo de usuário promovível é FULL ou RETWEETS_ONLY. Isso determina o tipo de conteúdo que pode ser promovido pela conta. Os anunciantes devem obter permissão para promover o conteúdo de outro usuário e entrar em contato com a X para que ele seja adicionado à sua conta como usuário promovível RETWEETS_ONLY.

Com as permissões configuradas corretamente, você pode fazer solicitações aos endpoints de produtos promovidos que fazem referência direta ao ID do Tweet que deseja promover. Use o endpoint POST accounts/:account_id/promoted-tweets para promover Tweets publicados e o endpoint POST accounts/:account_id/scheduled-promoted-tweets para promover Tweets agendados de outra conta do X Ads.

Você não precisa dar Retweet no Tweet de destino. Ao promover um Tweet com essa abordagem, o tweet_id retornado será diferente do ID do Tweet informado. Nos bastidores, o Tweet é republicado como um Tweet “nullcasted” por meio de Retweet e, em seguida, promovido. O tweet_id retornado corresponde a esse novo Tweet.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
count optional	Especifica quantos registros tentar recuperar por solicitação. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Especifica um cursor para obter a próxima página de resultados. Consulte Pagination para mais informações. Type: string Example: 8x7v00oow
promotable_user_ids optional	Limite a resposta apenas aos usuários promovíveis desejados, especificando uma lista de identificadores separados por vírgula. Até 200 IDs podem ser fornecidos. Type: string Example: l310s
sort_by optional	Ordena por um atributo compatível em ordem ascendente ou descendente. Consulte Sorting para mais informações. Type: string Example: created_at-asc
with_deleted optional	Inclui resultados excluídos na solicitação. Type: boolean Default: false Possible values: true, false
with_total_count optional	Inclui o atributo de resposta total_count. Observação: Este parâmetro e cursor são mutuamente exclusivos. Observação: Solicitações que incluem total_count terão limites de requisições mais baixos, atualmente definidos em 200 por 15 minutos. 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 um usuário promovível específico associado à conta atual.

O tipo de usuário promovível pode ser FULL ou RETWEETS_ONLY. Isso controla o tipo de conteúdo que a conta tem permissão para promover.

Os anunciantes devem obter permissão para promover o conteúdo de outro usuário. Desde que as permissões estejam configuradas corretamente, você pode fazer solicitações aos endpoints de produtos promovidos que referenciem diretamente o ID do Tweet que deseja promover.

Você não precisa dar Retweet no Tweet de destino. Ao promover um Tweet com essa abordagem, o tweet_id retornado será diferente do ID do Tweet fornecido. Nos bastidores, o Tweet é retuitado como um Tweet nullcast e, em seguida, promovido. O tweet_id retornado corresponde a esse novo Tweet.

URL do recurso

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

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, com exceção de GET accounts. A conta especificada deve estar associada ao usuário autenticado. Tipo: string Exemplo: 18ce54d4x5t
promotable_user_id opcional	Referência ao usuário promovível sobre o qual você está operando na solicitação. Tipo: string Exemplo: l310s
with_deleted opcional	Incluir resultados excluídos na solicitação. Tipo: boolean Padrão: false Valores possíveis: true, false

Exemplo de solicitação

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

Exemplo de resposta

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

​

Publicadores

Executar no Postman

​

GET publishers

Recupere uma lista com os detalhes dos publishers da categoria de conteúdo

Mais detalhes podem ser encontrados no Guia do objetivo de pré‑rolagem de Visualizações de Vídeo

Resource URL

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

Parameters

Nenhum parâmetro na requisição

Example Request

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

Example Response

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

​

Recomendações

Executar no Postman

​

GET accounts/:account_id/recommendations

Status: Beta fechada

Recupera recomendações de campanha associadas a esta conta de anúncios. Atualmente, há um limite de 1 recomendação por instrumento de financiamento.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. 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": "PENDENTE",
        "message": "Recomendação para teste"
        "created_at": "2016-11-14T23:07:54Z",
        "updated_at": "2016-11-14T23:07:54Z"
      }
    ]

​

GET accounts/:account_id/recommendations/:recommendation_id

Status: Beta fechado

Recupere uma recomendação de campanha específica associada a esta conta de anúncios.

A recomendação de campanha contém um conjunto completo de alterações sugeridas para a estrutura da campanha, representadas como uma árvore de objetos. A árvore de resposta foi projetada para funcionar em conjunto com os endpoints da Batch API, mas também pode ser mapeada para endpoints de atualização individuais, conforme apropriado (Create para POST, Update para PUT, Delete para DELETE).

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
recommendation_id required	Uma referência ao id da recomendação em que você está operando na solicitação 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": "Atualizar",
          "dependent_entities": [
            {
              "entity_type": "line_items",
              "params": {
                "name": "Campanha para recomendações",
                "placements": [
                  "TWITTER_TIMELINE"
                ],
                "bid_amount_local_micro": 1430000,
                "id": "6f5kq",
                "include_sentiment": "TODOS",
              },
              "operation_type": "Atualizar",
              "dependent_entities": [
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "id": "a8po6p"
                  },
                  "operation_type": null,
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "resultados das eleições",
                    "targeting_value": "resultados das eleições",
                    "targeting_type": "PHRASE_KEYWORD"
                  },
                  "operation_type": "Criar",
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "id": "101ftp"
                  },
                  "operation_type": "Excluir",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "Masculino",
                    "targeting_value": 1,
                    "targeting_type": "GENDER"
                  },
                  "operation_type": "Criar",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "San Francisco–Oakland–San Jose, CA, EUA",
                    "targeting_value": "",
                    "targeting_type": "LOCATION"
                  },
                  "operation_type": "Criar",
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "id": "101fto"
                  },
                  "operation_type": "Excluir",
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "line_item_id": "6f5kq",
                    "display_properties": [],
                    "paused": false,
                    "approval_status": "ACCEPTED",
                    "tweet_id": "91125952589766656"
                  },
                  "operation_type": "Criar",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "Segmentação de público de parceiros",
                    "targeting_value": "v2cx",
                    "targeting_type": "NEGATIVE_BEHAVIOR"
                  },
                  "operation_type": "Criar",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "IDADE_21_A_34",
                    "targeting_value": "IDADE_21_A_34",
                    "targeting_type": "AGE"
                  },
                  "operation_type": "Criar",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "id": "a8po6o"
                  },
                  "operation_type": "Excluir",
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "line_item_id": "6f5kq",
                    "display_properties": [],
                    "paused": false,
                    "approval_status": "ACCEPTED",
                    "tweet_id": "991101965843460096"
                  },
                  "operation_type": "Criar",
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "line_item_id": "6f5kq",
                    "display_properties": [],
                    "paused": false,
                    "approval_status": "ACCEPTED",
                    "tweet_id": "991127212156096516"
                  },
                  "operation_type": "Criar",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "debate",
                    "targeting_value": "debate",
                    "targeting_type": "NEGATIVE_PHRASE_KEYWORD"
                  },
                  "operation_type": "Criar",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "60004, IL, EUA",
                    "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": "PENDENTE",
      "message": "Recomendação para teste"
      "created_at": "2016-11-14T23:07:54Z",
      "updated_at": "2016-11-14T23:07:54Z"
      }
    }

​

Tweets promovidos agendados

Executar no Postman

​

GET accounts/:account_id/scheduled_promoted_tweets

Recupera detalhes de alguns ou de todos os Tweets promovidos agendados associados à conta atual.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
count optional	Especifica o número de registros a serem recuperados por solicitação. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Especifica um cursor para obter a próxima página de resultados. Consulte Pagination para mais informações. Type: string Example: 8x7v00oow
line_item_ids optional	Restringe a resposta apenas aos Tweets agendados associados a itens de linha específicos, informando uma lista de identificadores separados por vírgula. É possível fornecer até 200 IDs. Type: string Example: 8xdpe
scheduled_promoted_tweet_ids optional	Restringe a resposta apenas aos Tweets promovidos agendados desejados, informando uma lista de identificadores separados por vírgula. É possível fornecer até 200 IDs. Type: string Example: 1xboq
sort_by optional	Ordena por um atributo compatível, em ordem ascendente ou descendente. Consulte Sorting para mais informações. Type: string Example: created_at-asc
with_deleted optional	Inclui resultados excluídos na solicitação. Type: boolean Default: false Possible values: true, false
with_total_count optional	Inclui o atributo de resposta total_count. Note: Este parâmetro e cursor são mutuamente exclusivos. Note: Solicitações que incluem total_count terão limites de requisições menores, atualmente definidos em 200 por 15 minutos. Type: boolean Default: false Possible values: true, false

Example Request

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

Example Response

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

​

GET accounts/:account_id/scheduled_promoted_tweets/:scheduled_promoted_tweet_id

Recupera um Tweet promovido agendado específico associado à conta atual.

URL do recurso

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

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da API de Anunciantes, com exceção de GET accounts. A conta especificada deve estar associada ao usuário autenticado. Tipo: string Exemplo: 18ce54d4x5t
scheduled_promoted_tweet_id obrigatório	A referência ao Tweet promovido agendado com o qual você está operando na solicitação. Tipo: string Exemplo: 1xboq
with_deleted opcional	Incluir resultados excluídos na solicitação. Tipo: boolean Padrão: false Valores possíveis: true, false

Exemplo de solicitação

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

Exemplo de resposta

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

Associar um Tweet agendado ao item de linha especificado.

Observação: Não é possível atualizar (PUT) entidades de Tweet promovido agendado.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, com exceção de GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
line_item_id required	Uma referência ao item de linha com o qual você está operando na solicitação. Type: string Example: 8xdpe
scheduled_tweet_id required	Uma referência ao Tweet agendado com o qual você está operando na solicitação. 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

Desassocia um Tweet agendado do item de linha especificado.

Observação: scheduled_promoted_tweets só podem ser excluídos antes do horário scheduled_at do Tweet agendado.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
scheduled_promoted_tweet_id required	Uma referência ao Tweet promovido agendado com o qual você está operando na solicitação. Este é o atributo id de um objeto de resposta de GET accounts/:account_id/scheduled_promoted_tweets. Type: string Example: 1xtfl

Example Request

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

Example Response

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

​

Critérios de segmentação

Executar no Postman

​

GET accounts/:account_id/targeting_criteria

Recupere detalhes de alguns ou de todos os critérios de segmentação associados a itens de linha na conta atual.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta utilizada. Aparece no path do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, com exceção de GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
line_item_ids required	Restrinja a resposta apenas aos critérios de segmentação dos itens de linha especificados informando uma lista de identificadores separados por vírgula. Podem ser fornecidos até 200 IDs. Type: string Example: 8u94t
count optional	Especifica o número de registros a serem recuperados por solicitação. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Especifica um cursor para obter a próxima página de resultados. Consulte Pagination para mais informações. Type: string Example: 8x7v00oow
lang optional	Um código de idioma ISO-639-1. Quando fornecido, um atributo adicional localized_name será retornado na resposta para objetos em que um nome localizado estiver disponível. Type: string Example: fr
sort_by optional	Ordena por um atributo compatível em ordem crescente ou decrescente. Consulte Sorting para mais informações. Type: string Example: created_at-asc
targeting_criterion_ids optional	Restrinja a resposta apenas aos critérios de segmentação desejados informando uma lista de identificadores separados por vírgula. Podem ser fornecidos até 200 IDs. Type: string Example: dpl3a6
with_deleted optional	Inclua resultados excluídos na solicitação. Type: boolean Default: false Possible values: true, false
with_total_count optional	Inclua o atributo de resposta total_count. Observação: Este parâmetro e cursor são mutuamente exclusivos. Observação: Solicitações que incluam total_count terão limites de requisições menores, atualmente definidos em 200 por 15 minutos. 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": "Segmentação por audiência personalizada",
          "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

Recupere um critério de segmentação específico associado à conta atual.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, com exceção de GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
targeting_criterion_id required	Uma referência ao critério de segmentação com o qual você está operando na solicitação. Type: string Example: eijd4y
lang optional	Um código de idioma ISO-639-1. Quando enviado, um atributo adicional localized_name será retornado na resposta para objetos em que houver um nome localizado disponível. Type: string Example: fr
with_deleted optional	Inclui resultados excluídos na sua solicitação. 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": "PALAVRA_CHAVE_AMPLA"
      }
    }

​

POST accounts/:account_id/targeting_criteria

Consulte a página Targeting Options para encontrar targeting_values para tipos específicos de segmentação. Recomendamos atualizar todos os dados semanalmente para garantir que você esteja trabalhando com o conjunto mais recente de valores de tipos de segmentação. Alteramos valores e critérios de segmentação disponíveis de tempos em tempos; embora a maioria deles não mude com frequência, alguns mudam. Não há garantia de que esses valores não mudarão.

Use os tipos de segmentação BROAD_KEYWORD, EXACT_KEYWORD, PHRASE_KEYWORD ou UNORDERED_KEYWORD com as palavras-chave especificadas em targeting_value. Exclua palavras-chave usando o parâmetro de solicitação operator_type definido como NE. Consulte targeting keyword types para uma descrição detalhada de cada tipo.

Observação: Só é possível segmentar um único intervalo de idade por item de linha.

Observação: Para segmentar uma Custom Audience, esse público deve ser segmentável. Ou seja, targetable deve ser igual a true.

Observação: Ao usar o tipo de segmentação TV_SHOW, deve haver pelo menos um critério de segmentação LOCATION no item de linha antes de definir a segmentação TV_SHOW, e todos os LOCATION devem estar no mesmo locale que o TV_SHOW sendo segmentado.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
line_item_id required	Uma referência ao item de linha com o qual você está operando na solicitação. Type: string Example: 69ob
operator_type required	Especifique a relação que o critério de segmentação deve ter. Por exemplo, para excluir palavras-chave, use operator_type=NE. Type: enum Possible values: EQ, NE, GTE, LT
targeting_type required	O tipo de segmentação que será aplicado a este item de linha. 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 Observação: Só é possível segmentar um único intervalo AGE por item de linha. 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 (may only be used with operator_type=NE)
targeting_value required	Especifique qual usuário, qual interesse, qual localização, qual evento, qual plataforma, qual versão da plataforma, qual dispositivo, qual palavra-chave ou frase, qual gênero, qual custom audience, qual categoria da app store ou qual exclusão de uma lista de apps receberá esta segmentação, dependendo do targeting_type selecionado. 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

Exemplo de resposta

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

Permite criar em lote novos Targeting Criteria com uma única solicitação.

Solicitações em lote

• O tamanho máximo atual do lote é 500.
• Todos os parâmetros são enviados no corpo da solicitação e é necessário Content-Type: application/json.
• Solicitações em lote falham ou têm sucesso juntas, como um grupo, e todas as respostas da API — tanto de erro quanto de sucesso — preservam a ordem dos itens da solicitação inicial.

Respostas em lote

As respostas da API em lote retornam uma coleção ordenada de itens. No mais, são idênticas, em estrutura, aos seus endpoints correspondentes de item único.

Erros em lote

• Erros no nível da solicitação (por exemplo, estouro do tamanho máximo do lote) são exibidos na resposta no objeto errors.
• Erros no nível do item (por exemplo, parâmetro obrigatório de Targeting Criteria ausente) são exibidos na resposta no objeto operation_errors.

Resource URL

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

Parameters

Name	Description
operation_type required	O tipo de operação por item que está sendo executado. Type: enum Possible values: Create, Delete
params required	Um objeto JSON contendo todos os parâmetros dos objetos de targeting criteria. Para uma lista de parâmetros obrigatórios e opcionais de targeting criteria, consulte aqui. Além disso, este endpoint oferece suporte ao parâmetro operator_type, que funciona em conjunto com determinados valores de targeting_type. Os valores possíveis para esse parâmetro são EQ (igual a), GTE (maior ou igual a), LT (menor que) e NE (diferente de).

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

Exemplo de resposta

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

Exclui o critério de segmentação especificado pertencente à conta atual.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, com exceção de GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
targeting_criterion_id required	Uma referência ao critério de segmentação com o qual a solicitação está operando. Type: string Example: dpl3a6

Example Request

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

Example Response

    {
      "data": {
        "line_item_id": "8u94t",
        "name": "Segmentação por audiência personalizada",
        "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"
        }
      }
    }

​

Opções de segmentação

Executar no Postman

• Categorias da App Store
• Conversas
• Dispositivos
• Eventos
• Interesses
• Idiomas
• Localizações
• Operadoras de rede
• Versões da plataforma
• Plataformas
• Mercados de TV
• Programas de TV

​

GET targeting_criteria/app_store_categories

Descubra os critérios de segmentação disponíveis por categoria de loja de apps para Produtos Promovidos. As categorias de lojas de apps estão disponíveis apenas para a App Store do iOS e a Google Play Store.

A segmentação por categoria de apps instalados permite alcançar usuários com base nas categorias de apps que eles instalaram ou pelas quais demonstraram interesse.

Resource URL

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

Parameters

Name	Description
q optional	Uma query opcional para limitar um critério de segmentação. Omita este parâmetro para recuperar todos. Type: string Example: music
os_type optional	Limite os resultados a uma loja de apps específica. 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": "Jogos: Música",
          "targeting_type": "APP_STORE_CATEGORY",
          "targeting_value": "qouq",
          "os_type": "IOS"
        },
        {
          "name": "Música",
          "targeting_type": "APP_STORE_CATEGORY",
          "targeting_value": "qov2",
          "os_type": "IOS"
        }
      ],
      "request": {
        "params": {
          "q": "música"
          "os_type": "IOS"
        }
      }
    }

​

GET targeting_criteria/conversations

Descubra os critérios de segmentação baseados em conversas disponíveis para Produtos Promovidos.

Resource URL

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

Parameters

Name	Description
conversation_type optional	Uma query opcional para restringir a um determinado tipo de conversa. Type: enum Valores possíveis: ACTORS, ATHLETES, BOOK_GENRES, BOOKS, BRAND_CATEGORIES, BRANDS, CELEBRITIES, COACHES, DIGITAL_CREATORS, ENTERTAINMENT_BRANDS, ENTERTAINMENT_PERSONALITIES, FICTIONAL_CHARACTERS, JOURNALISTS, LIFESTYLES, MOVIE_GENRES, MOVIES, MUSIC_GENRES, MUSICIANS, NEWS_STORIES, NEWS, PERSONS, PLACES, PODCASTS, POLITICAL_AFFILIATIONS, POLITICIANS, PRODUCTS, RADIO_STATIONS, SPORTS_LEAGUES, SPORTS_PERSONALITIES, SPORTS_TEAMS, SPORTS, TRENDS, TV_SHOWS, VIDEO_GAME_PLATFORMS, VIDEO_GAME_PUBLISHERS, VIDEO_GAMES
count optional	Especifica o número de registros a recuperar por solicitação distinta. Type: int Padrão: 200 Mín., máx.: 1, 1000
cursor optional	Especifica um cursor para obter a página seguinte de resultados. Consulte Pagination para mais informações. Type: string Exemplo: 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

Conheça os critérios de segmentação por dispositivo disponíveis para Promoted Products. A segmentação por dispositivo está disponível para Promoted Tweets.

Resource URL

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

Parameters

Name	Description
count opcional	Especifica o número de registros a serem recuperados por solicitação distinta. Type: int Default: 200 Min, Max: 1, 1000
q opcional	Uma query opcional para delimitar um critério de segmentação. Omita este parâmetro para recuperar todos. 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

Descubra os critérios de segmentação baseados em eventos disponíveis para Promoted Products. Apenas um evento pode ser segmentado por line item.

Observação: Eventos costumam ocorrer em múltiplos fusos horários, o que pode gerar complicações ao considerar seus horários em perspectivas entre fusos. Para simplificar, todos os valores de start_time e end_time de eventos neste endpoint são representados em UTC±00:00, independentemente do local e do fuso horário do evento. Esse design deve ser considerado ao consultar e interagir com os valores de start_time e end_time dos eventos. Por exemplo, o Independence Day dos EUA é representado como start_time=2017-07-04T00:00:00Z e end_time=2017-07-05T00:00:00Z em UTC±00:00, evitando assim o problema desse feriado abranger vários fusos horários nos EUA.

Resource URL

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

Parameters

Name	Description
event_types required	Uma query opcional para limitar a determinados tipos de evento. Type: enum Valores possíveis: CONFERENCE, HOLIDAY, MUSIC_AND_ENTERTAINMENT, OTHER, POLITICS, RECURRING, SPORTS
count optional	Especifica o número de registros a recuperar por solicitação. Type: int Padrão: 200 Mín., máx.: 1, 1000
country_codes optional	Uma query opcional para limitar a pesquisa de critérios de segmentação a países específicos, usando o código de país ISO de 2 letras. Se este parâmetro não for especificado, todos os eventos serão retornados. Type: string
cursor optional	Especifica um cursor para obter a próxima página de resultados. Consulte Pagination para mais informações. Type: string Exemplo: 8x7v00oow
end_time optional	O horário, expresso em ISO 8601, em que a campanha terminará. Type: string Exemplo: 2017-10-05T00:00:00Z
start_time optional	O horário, expresso em ISO 8601, em que o line item começará a veicular. Observação: Padrão: horário atual. Type: string Exemplo: 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": "Ano Novo",
          "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

Descubra os critérios de segmentação por interesse disponíveis para Produtos Promovidos. Os interesses mudam raramente; ainda assim, recomendamos atualizar esta lista pelo menos uma vez por semana.

Resource URL

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

Parameters

Name	Description
count optional	Especifica quantos registros tentar recuperar por solicitação. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Especifica um cursor para obter a próxima página de resultados. Consulte Pagination para mais informações. Type: string Example: 8x7v00oow
q optional	Uma query opcional para delimitar os critérios de segmentação. Omita este parâmetro para recuperar todos. Type: string Example: books

Example Request

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

Example Response

    {
      "data": [
        {
          "name": "Livros e literatura/Biografias e memórias",
          "targeting_type": "INTEREST",
          "targeting_value": "1001"
        }
      ],
      "request": {
        "params": {
          "q": "livros",
          "count": 1
        }
      },
      "next_cursor": "6by4n4"
    }

​

GET targeting_criteria/languages

Conheça os idiomas disponíveis para segmentação.

URL do recurso

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

Parâmetros

Name	Description
count optional	Especifica o número de registros a recuperar por solicitação. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Especifica um cursor para obter a próxima página de resultados. Consulte Paginação para mais informações. Type: string Example: 8x7v00oow
q optional	Uma query opcional para delimitar um critério de segmentação. Omita este parâmetro para recuperar todos. Type: string Example: english

Exemplo de solicitação

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

Exemplo de resposta

    {
      "data": [
        {
          "name": "Inglês",
          "targeting_type": "LANGUAGE",
          "targeting_value": "en"
        }
      ],
      "request": {
        "params": {
          "q": "inglês"
        }
      },
      "next_cursor": null
    }

​

GET targeting_criteria/locations

Descubra os critérios de segmentação por localização disponíveis para Produtos Promovidos. A segmentação geográfica está disponível para Promoted Accounts e Promoted Tweets nos níveis de país, estado/região, cidade e código postal. A segmentação por código postal deve ser usada se você quiser obter análises no nível de código postal.

Observação: Para recuperar cidades específicas segmentáveis, como San Francisco ou New York, use o enum CITIES com o parâmetro de solicitação location_type.

Para segmentar Designated Market Areas (DMAs), use o enum METROS.

Resource URL

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

Parameters

Name	Description
count optional	Especifica quantos registros tentar obter por solicitação distinta. Type: int Default: 200 Min, Max: 1, 1000
country_code optional	Uma query opcional para limitar a pesquisa de critérios de segmentação a um país específico usando o código ISO de 2 letras. Omita este parâmetro para recuperar resultados de todos os países. Type: string Example: JP
cursor optional	Especifica um cursor para obter a próxima página de resultados. Consulte Pagination para mais informações. Type: string Example: 8x7v00oow
location_type optional	Limite os resultados por um tipo específico de localização. Uma segmentação mais granular do que COUNTRIES pode não estar disponível em todas as localidades. Type: enum Possible values: COUNTRIES, REGIONS, METROS, CITIES, POSTAL_CODES
q optional	Uma query opcional para limitar a pesquisa de critérios de segmentação. Omita este parâmetro para recuperar todos os resultados. 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, EUA",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "3b77caf94bfc81fe",
          "targeting_type": "LOCATION"
        },
        {
          "name": "East Los Angeles, Los Angeles, CA, EUA",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "67571a7baaa5906b",
          "targeting_type": "LOCATION"
        },
        {
          "name": "Lake Los Angeles, Los Angeles, CA, EUA",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "ea9bfbd43c93400f",
          "targeting_type": "LOCATION"
        },
        {
          "name": "Los Gatos, San Francisco–Oakland–San Jose, CA, EUA",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "a2de7c70b82b0ca0",
          "targeting_type": "LOCATION"
        },
        {
          "name": "Los Altos, Monterey–Salinas, CA, EUA",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "6a4364ea6f987c10",
          "targeting_type": "LOCATION"
        },
        {
          "name": "Los Baños, CA, EUA",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "b1b6fc646de75904",
          "targeting_type": "LOCATION"
        },
        {
          "name": "Los Alamitos, Los Angeles, CA, EUA",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "0799ff0a3c1006e9",
          "targeting_type": "LOCATION"
        },
        {
          "name": "Los Angeles, EUA",
          "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

Descubra os critérios de segmentação disponíveis com base em operadoras de rede para Produtos Promovidos.

Este endpoint permite consultar operadoras segmentáveis, como AT&T, Verizon, Sprint, T-Mobile etc., em vários países.

Resource URL

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

Parameters

Name	Description
count optional	Especifica o número de registros a serem recuperados por solicitação. Type: int Default: 200 Min, Max: 1, 1000
country_code optional	Uma query opcional para restringir a busca de critérios de segmentação a um país específico usando o código ISO de país com 2 letras. Se este parâmetro não for especificado, somente audiências de parceiros dos Estados Unidos serão retornadas. Type: string Default: US
cursor optional	Especifica um cursor para obter a próxima página de resultados. Consulte Pagination para mais informações. Type: string Example: 8x7v00oow
q optional	Uma query opcional para restringir a busca de critérios de segmentação. Omita este parâmetro para recuperar todos os resultados. 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

Descubra os critérios de segmentação disponíveis por versão de sistema operacional móvel para Produtos Promovidos. A segmentação por versão de plataforma está disponível para Contas Promovidas e Tweets Promovidos. Isso permite segmentar até a versão pontual de um sistema operacional móvel, como Android 8.0 ou iOS 10.0.

Resource URL

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

Parameters

Name	Description
q optional	Uma query opcional para restringir a busca por critérios de segmentação. Omita este parâmetro para recuperar todos os resultados. Type: string Examples: jelly bean

Example Request

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

Example Response

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

​

GET targeting_criteria/platforms

Descubra os critérios de segmentação por plataforma disponíveis para Produtos Promovidos.

Resource URL

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

Parameters

Name	Description
count optional	Especifica o número de registros a serem recuperados por solicitação. Type: int Default: 200 Min, Max: 1, 1000
q optional	Parâmetro query opcional para delimitar a busca de critérios de segmentação. Omita este parâmetro para recuperar todos os resultados. Type: string Examples: ios, blackberry
lang optional	Código de idioma ISO-639-1. Quando informado, um atributo adicional localized_name será retornado na resposta. 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": "Aparelhos e tablets BlackBerry",
          "targeting_type": "PLATFORM",
          "targeting_value": "2"
        },
        {
          "name": "Web móvel em outros dispositivos",
          "targeting_type": "PLATFORM",
          "targeting_value": "3"
        },
        {
          "name": "Computadores de mesa e laptops",
          "targeting_type": "PLATFORM",
          "targeting_value": "4"
        }
      ],
      "request": {
        "params": {}
      }
    }

​

GET targeting_criteria/tv_markets

Descubra os mercados de TV disponíveis nos quais programas de TV podem ser segmentados. Retorna mercados por localidade que podem ser usados para consultar o endpoint GET targeting_criteria/tv_shows.

URL do recurso

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

Parâmetros

Nenhum

Exemplo de solicitação

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

Exemplo de resposta

    {
      "data": [
        {
          "name": "França",
          "country_code": "FR",
          "locale": "fr-FR"
        },
        {
          "name": "Chile",
          "country_code": "CL",
          "locale": "es-CL"
        },
        {
          "name": "Alemanha",
          "country_code": "DE",
          "locale": "de-DE"
        },
        {
          "name": "Países Baixos",
          "country_code": "NL",
          "locale": "nl-NL"
        },
        {
          "name": "Estados Unidos",
          "country_code": "US",
          "locale": "en-US"
        },
        {
          "name": "Venezuela",
          "country_code": "VE",
          "locale": "es-VE"
        },
        {
          "name": "Brasil",
          "country_code": "BR",
          "locale": "pt-BR"
        },
        {
          "name": "México",
          "country_code": "MX",
          "locale": "es-MX"
        },
        {
          "name": "Colômbia",
          "country_code": "CO",
          "locale": "es-CO"
        },
        {
          "name": "Reino Unido",
          "country_code": "GB",
          "locale": "en-GB"
        },
        {
          "name": "Argentina",
          "country_code": "AR",
          "locale": "es-AR"
        },
        {
          "name": "Japão",
          "country_code": "JP",
          "locale": "ja-JP"
        },
        {
          "name": "Canadá",
          "country_code": "CA",
          "locale": "en-CA"
        },
        {
          "name": "Espanha",
          "country_code": "ES",
          "locale": "es-ES"
        },
        {
          "name": "Itália",
          "country_code": "IT",
          "locale": "it-IT"
        },
        {
          "name": "Estados Unidos — Hispânico",
          "country_code": "US",
          "locale": "es-US"
        },
        {
          "name": "Irlanda"
          "country_code": "IE",
          "locale": "en-IE"
        }
      ],
      "request": {
        "params": {}
      }
    }

​

GET targeting_criteria/tv_shows

Descubra os critérios de segmentação disponíveis com base em programas de TV para Produtos Promovidos. A segmentação por programas de TV está disponível para Tweets Promovidos em determinados mercados. Consulte o endpoint GET targeting_criteria/tv_markets para ver os mercados disponíveis.

Observação: Qualquer público com menos de 1.000 usuários será exibido com o valor estimated_users igual a 1000.

Observação: As opções de segmentação por canal de TV e gênero não são mais compatíveis.

Resource URL

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

Parameters

Name	Description
locale required	Parâmetro obrigatório que especifica o tv_market_locale para consultar os programas de TV disponíveis. Os mercados de TV são consultados com base no locale retornado por GET targeting_criteria/tv_markets. Type: string Example: en-US
count optional	Especifica o número de registros a serem recuperados por solicitação. Type: int Default: 50 Min, Max: 1, 50
cursor optional	Especifica um cursor para obter a próxima página de resultados. Consulte Pagination para mais informações. Type: string Example: 8x7v00oow
q optional	Uma query opcional para delimitar a busca de critérios de segmentação. Omita este parâmetro para recuperar todos os resultados. 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"
        }
      }
    }

​

Sugestões de segmentação

Executar no Postman

​

GET accounts/:account_id/targeting_suggestions

Obtenha até 50 sugestões de segmentação por palavra-chave ou por usuário para complementar sua seleção inicial.

Resource URL

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

Parameters

Name	Description
account_id required	Identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
suggestion_type required	Especifique o tipo de sugestão a retornar. Type: enum Possible values: KEYWORD, USER_ID
targeting_values required	Coleção, separada por vírgulas, de palavras-chave ou IDs de usuário usada para gerar as sugestões. Note: Esses dois tipos de sugestão não podem ser misturados. Example: 756201191646691328
count optional	Especifica a quantidade de registros a tentar recuperar por solicitação. Type: int Default: 30 Min, Max: 1, 50

Example Request

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

Example Response

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

​

Configurações de Imposto

Executar no Postman

​

GET accounts/:account_id/tax_settings

Recupera os detalhes das configurações fiscais associadas à conta atual.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto em GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t

Example Request

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

Example Response

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

​

PUT accounts/:account_id/tax_settings

Atualiza as configurações fiscais da conta atual.

URL do recurso

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

Parâmetros

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto em GET accounts. A conta especificada deve estar associada ao usuário autenticado. Tipo: string Exemplo: 18ce54d4x5t
address_city optional	A cidade do endereço do proprietário da conta. Tipo: string Exemplo: San Francisco
address_country optional	O código de país de duas letras do endereço do proprietário da conta. Tipo: string Exemplo: US
address_email optional	O e-mail associado ao endereço do proprietário da conta. Tipo: string Exemplo: [e-mail]
address_first_name optional	O primeiro nome do proprietário da conta para o endereço. Tipo: string Exemplo: API
address_last_name optional	O sobrenome do proprietário da conta para o endereço. Tipo: string Exemplo: McTestface
address_name optional	O nome da empresa no endereço do proprietário da conta. Tipo: string Exemplo: ABC, Co.
address_postal_code optional	O código postal do endereço do proprietário da conta. Tipo: string Exemplo: 94102
address_region optional	A região do endereço do proprietário da conta. Tipo: string Exemplo: California
address_street1 optional	A primeira linha do endereço do proprietário da conta. Tipo: string Exemplo: 21 March St
address_street2 optional	A segunda linha do endereço do proprietário da conta. Tipo: string Exemplo: Suite 99
bill_to optional	A entidade a ser faturada. Tipo: enum Valores possíveis: ADVERTISER, AGENCY
business_relationship optional	Se a conta pertence ao anunciante ou à agência. Tipo: enum Valores possíveis: AGENCY, SELF
client_address_city optional	A cidade do endereço do anunciante. Defina quando a conta de anúncios pertencer a uma agência. Tipo: string Exemplo: Toronto
client_address_country optional	O código de país de duas letras do endereço do anunciante. Defina quando a conta de anúncios pertencer a uma agência. Tipo: string Exemplo: CA
client_address_email optional	O e-mail associado ao endereço do anunciante. Defina quando a conta de anúncios pertencer a uma agência. Tipo: string Exemplo: [e-mail]
client_address_first_name optional	O primeiro nome do anunciante para o endereço. Defina quando a conta de anúncios pertencer a uma agência. Tipo: string Exemplo: Brand
client_address_last_name optional	O sobrenome do anunciante para o endereço. Defina quando a conta de anúncios pertencer a uma agência. Tipo: string Exemplo: Advertiser
client_address_name optional	O nome da empresa no endereço do anunciante. Defina quando a conta de anúncios pertencer a uma agência. Tipo: string Exemplo: Brand, Inc.
client_address_postal_code optional	O código postal do endereço do anunciante. Defina quando a conta de anúncios pertencer a uma agência. Tipo: string Exemplo: M5H 2N2
client_address_region optional	A região do endereço do anunciante. Defina quando a conta de anúncios pertencer a uma agência. Tipo: string Exemplo: Ontario
client_address_street1 optional	A primeira linha do endereço do anunciante. Defina quando a conta de anúncios pertencer a uma agência. Tipo: string Exemplo: 280 Queen St W
client_address_street2 optional	A segunda linha do endereço do anunciante. Defina quando a conta de anúncios pertencer a uma agência. Tipo: string Exemplo: The 6
invoice_jurisdiction optional	Jurisdição da fatura. Tipo: enum Valores possíveis: LOI_SAPIN, NONE, NOT_SET
tax_category optional	Se a tributação deve ser individual ou empresarial. Tipo: enum Valores possíveis: BUSINESS_NO_VAT, BUSINESS_WITH_VAT, INDIVIDUAL
tax_exemption_id optional	ID de isenção de VAT. Tipo: string Exemplo: 12345
tax_id optional	ID de registro de VAT. Tipo: string Exemplo: 67890

Exemplo de solicitação

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

Exemplo de resposta

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

​

Tags de acompanhamento

Executar no Postman

​

GET accounts/:account_id/tracking_tags

Recupere detalhes de algumas ou todas as tags de rastreamento associadas à conta atual.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto em GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
count optional	Especifica o número de registros a serem recuperados por solicitação. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Especifica um cursor para obter a próxima página de resultados. Consulte Pagination para mais informações. Type: string Example: 8x7v00oow
line_item_ids optional	Restrinja a resposta apenas às tags de rastreamento associadas a itens de linha específicos, informando uma lista de identificadores separada por vírgulas. É possível fornecer até 200 IDs. Type: string Example: 96uzp
sort_by optional	Ordena por um atributo compatível em ordem ascendente ou descendente. Consulte Sorting para mais informações. Type: string Example: created_at-asc
tracking_tag_ids optional	Restrinja a resposta apenas às tags de rastreamento desejadas, informando uma lista de identificadores separada por vírgulas. É possível fornecer até 200 IDs. Type: string Example: 3m82
with_deleted optional	Inclua resultados excluídos na solicitação. Type: boolean Default: false Possible values: true, false
with_total_count optional	Inclua o atributo de resposta total_count. Observação: Este parâmetro e cursor são mutuamente exclusivos. Observação: Solicitações que incluem total_count terão limites de requisições menores, atualmente definidos em 200 por 15 minutos. 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 uma tag de rastreamento específica associada à conta atual.

URL do recurso

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

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, com exceção de GET accounts. A conta especificada deve estar associada ao usuário autenticado. Tipo: string Exemplo: 18ce54d4x5t
tracking_tag_id obrigatório	Referência à tag de rastreamento com a qual você está operando na solicitação. Tipo: string Exemplo: 555j
with_deleted opcional	Inclui resultados excluídos na solicitação. Tipo: boolean Padrão: false Valores possíveis: true, false

Exemplo de solicitação

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

Exemplo de resposta

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

Associar uma tag de rastreamento ao item de linha especificado.

URL do recurso

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

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
line_item_id obrigatório	Uma referência ao item de linha com o qual você está operando na solicitação. Type: string Example: 8v7jo
tracking_tag_type obrigatório	O tipo de tag de rastreamento. Type: enum Possible value: IMPRESSION_TAG, CLICK_TRACKER
tracking_tag_url obrigatório	A URL da tag de rastreamento fornecida pelo parceiro de rastreamento. Type: string Example: https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309

Exemplo de solicitação

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

Exemplo de resposta

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

Associar uma tag de rastreamento ao line item especificado.

URL do recurso

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

Parâmetros

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
tracking_tag_url required	A URL da tag de rastreamento fornecida pelo parceiro de rastreamento. Type: string Example: https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309

Exemplo de solicitação

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

Exemplo de resposta

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

Desassocia uma tag de rastreamento do item de linha especificado.

URL do recurso

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

Parâmetros

Nome	Descrição
account_id obrigatório	Identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto em GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
tracking_tag_id obrigatório	Referência à tag de rastreamento usada na solicitação. Type: string Example: 555j

Exemplo de solicitação

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

Exemplo de resposta

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

​

Configurações do usuário

Executar no Postman

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

​

GET accounts/:account_id/user_settings/:user_id

Recupera as configurações do usuário.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta alavancada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, com exceção de GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
user_id required	Uma referência ao usuário com o qual você está operando na solicitação. Use GET users/lookup para recuperar o id de um usuário a partir de um screen name. Type: long Example: 756201191646691328

Example Request

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

Example Response

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

Atualiza as configurações do usuário. Requer contexto de usuário. Não acessível por administradores da conta.

Resource URL

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

Parameters

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e em GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
user_id required	Referência ao usuário em nome de quem você está realizando a solicitação. Use GET users/lookup para recuperar o id de um usuário a partir do screen name. Type: long Example: 756201191646691328
notification_email optional	E-mail a ser usado para notificações da conta. Type: string Example: [e-mail]
contact_phone optional	Número de telefone para contato. Type: string Example: 202-555-0128
contact_phone_extension optional	Ramal do contact_phone. Type: string Example: 1234

Example Request

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

Example Response

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