Audiências

​

Audiências personalizadas

​

Visão geral

Há várias maneiras de parceiros criarem Custom Audiences.

• Audience API (CRM)
• Web
• Mobile
• Flexível

Observe que não é possível excluir custom audiences lookalike do direcionamento. Além disso, não é possível direcionar simultaneamente uma custom audience e uma custom audience lookalike no mesmo item de linha de anúncio (grupo de anúncios).

Gerenciamento de audiências

As audiências podem ser gerenciadas por parceiros de audiência e parceiros da X Ads API. Oferecemos uma série de endpoints na API para acessar e manter custom audiences.

Para informações sobre custom audiences, oferecemos 2 endpoints:

• GET accounts/:account_id/custom_audiences
• GET accounts/:account_id/custom_audiences/:custom_audience_id

Para mais detalhes sobre como enviar e gerenciar audiências, consulte o guia da Audience API.

Tempos de processamento

De modo geral, as alterações de audiência são processadas em lotes executados a cada 6–8 horas. Enquanto uma alteração de audiência está em processamento, a audiência existente a ser atualizada não é afetada. Não recomendamos fazer mais de uma atualização de adições e uma atualização de remoções por audiência dentro desse período.

Direcionamento

Uma audiência só pode ser direcionada se corresponder a pelo menos 100 users ativos nos últimos 90 dias em clientes de propriedade e operação da X. GET accounts/:account_id/custom_audiences/:custom_audience_id indicará se uma audiência não pode ser direcionada porque corresponde a poucos users.

Audience API (CRM)

Parceiros de audiência ou de API fornecem uma lista de identificadores com hash, e a X realiza a correspondência e produz segmentos que ficam disponíveis para compra de mídia na X. Os parceiros podem criar essas audiências com a Audience API.

Como funciona?

Web

Oferecemos um processo padrão de correspondência de cookies ao trabalhar com parceiros de audiência MPP para identificar segmentos a serem direcionados na compra de mídia na X. Além disso, os anunciantes podem configurar uma X Web Event Tag para coletar dados de usuários do site e criar uma Custom Audience correspondente.

Etapas de configuração

Como funciona?

Mobile

Consulte a postagem do blog Custom Audiences from Mobile Apps para obter detalhes.

Flexível

Flexible audiences dão aos anunciantes a capacidade de criar e salvar combinações de audiência com base em custom audiences existentes ou subconjuntos de custom audiences existentes. Subconjuntos dos membros de uma custom audience podem ser direcionados com base na recência e na frequência de interação.

Casos de uso restritos para Custom Audiences

Leia mais sobre restrições

​

Perguntas frequentes sobre públicos

P: Enviamos uma grande quantidade de dados; por que o tamanho do público aparece como TOO_SMALL?

R: No momento, os dados estão sendo adicionados ao público em tempo real, mas o job que processa os dados para calcular o tamanho do público só é executado após um período. O tamanho correto do público deve ser exibido na interface após algumas horas.

P: Terminamos de enviar os dados do público e esperamos 24 horas ou mais, mas ainda não conseguimos segmentar o público — quais devem ser os próximos passos?

R: Confirme o seguinte:

• O user ID enviado está correto e não está com formatação inválida.
• Os nomes dos públicos enviados estão corretos e correspondem às atualizações de associação anteriores.
• Confirme a resposta dos comandos POST.
• Confirme se o pixel de ID Sync está implementado corretamente e, conforme descrito pelo processo de ID Sync, se usuários suficientes visitaram o site em questão para mapear usuários. Usuários não mapeados nas atualizações de associação não serão convertidos em usuários segmentáveis.

Se todo o restante estiver correto e funcionando, entre em contato com os responsáveis pelo produto da X com informações o mais detalhadas possível (consulte Guide to Partner Inbounds para um exemplo do tipo de informação preferida).

P: Quantas vezes podemos chamar o endpoint e com qual algoritmo?

R: Recomendamos fortemente que você chame nosso sistema com deltas incrementais e nunca reenvie toda a associação do público. O sistema foi testado para ter uma taxa de transferência suficiente para processar atualizações incrementais de dados para alguns dos maiores sites do mundo. O upload inicial dos públicos deve ser cuidadosamente controlado e o primeiro envio deve levar um tempo significativo para ser concluído.

P: Qual é o tamanho mínimo de um público para ser usado em segmentação?

• O tamanho mínimo de um público é 100 usuários (após a correspondência). Se um público com menos de 500 usuários for correspondido, ele não estará disponível para segmentação na X Ads UI.

P: Quanto tempo leva para processar os arquivos de público? E quanto tempo leva para os arquivos de público ficarem prontos na interface da X?

• Normalmente, leva de 4 a 6 horas para processar os arquivos de público, mas isso dependerá do tamanho do arquivo. Assim que o arquivo for processado, os públicos ficam disponíveis na X Ads UI.

P: Como a taxa de correspondência é calculada?

• Taxa de correspondência = usuários ativos na X em 90 dias / número de usuários fornecidos

P: Como testamos se um arquivo de público está funcionando corretamente?

• Você pode fornecer um arquivo de público de teste e usar “keltonlynn” como o handle do anunciante. Podemos então verificar se o arquivo pode ser devidamente ingerido e carregado na X UI.

P: O que é um identificador de usuário parceiro (p_user_id)?

• É o identificador usado pela sua empresa para identificar de forma exclusiva cada um de seus clientes.

P: O que é um ID padrão?

• Pode ser um endereço de e-mail, device ID, X @handle ou ID.

P: Como obtenho a HMAC Key?

• Ela será fornecida por e-mail criptografado. Envie sua chave PGP pública para [e-mail] e enviaremos um e-mail de teste para verificar se tudo está funcionando. Depois de verificado, enviaremos a HMAC Key.

P: Como verifico que o processo de hashing funcionou usando a HMAC Key fornecida?

• A X fornecerá um arquivo de teste (contendo endereços de e-mail de exemplo, device IDs etc.) e um arquivo de hash resultante para você comparar e validar seus resultados.

P: Há uma limitação de tamanho de arquivo para o arquivo de correspondência de dados completo?

• Não, não há limitação de tamanho para o arquivo de correspondência de dados completo.

P: Quanto tempo levará para o arquivo de correspondência de dados completo ser processado?

• Depois que o arquivo for recebido pela X, levará aproximadamente 1 dia para processá-lo.

​

CRM

Este documento descreve os detalhes de integração para parceiros de CRM de Custom Audiences, incluindo formatos de arquivo e o processo de troca de dados.

Resumo

A empresa fornecerá uma lista de identificadores de usuário comuns com hash (por exemplo, endereços de e‑mail) ou ids de usuário do parceiro, em nome de um cliente, para que a X realize uma correspondência às cegas e produza uma lista de X User IDs para segmentação. Os segmentos de segmentação ficarão disponíveis para o @handle específico do anunciante, definido pelo nome do arquivo na configuração da campanha em ads.x.com.

Todos os arquivos da empresa serão enviados à X por meio de um pacote seguro no IronBox (www.golockbox.com), utilizando uma conta específica concedida à empresa pela X. A X fornecerá acesso ao IronBox. A documentação das APIs do IronBox pode ser encontrada em https://secure.goironcloud.com/Docs/Help/.

​

Requisitos de correspondência de ID de parceiro

Se a empresa usar seu próprio sistema padrão de IDs para rastrear usuários (ou seja, não identificadores comuns de usuário como endereços de e‑mail, device ids, X user ID etc.), este é o processo recomendado.

1. Correspondência completa de dados

Inicialmente, a empresa fornecerá uma lista abrangente de todos os registros de usuários que inclua um identificador comum de usuário exclusivo com a X em um único arquivo, para realizar uma correspondência completa de dados e produzir um mapeamento, armazenado pela X, de IDs de parceiro (p_user_id) para IDs da X (tw_id). Isso será feito regularmente a cada 2–3 meses para garantir a devida manutenção. Após a conclusão da correspondência, a X compartilhará com a empresa, por e‑mail, uma taxa de correspondência de referência obtida a partir desse arquivo.

O formato desse arquivo deve ser:

Convenção de nome: FullDataMatch.[CompanyName].txt

Algoritmo de hash: HMAC_SHA-256

Formato:

Coluna 1: valor HMAC com hash dos identificadores comuns

Coluna 2: Partner User ID (exclusivo por usuário, pode se repetir no arquivo)

Delimitador de colunas (CSV): vírgulas serão usadas para delimitar o identificador comum de usuário com hash do Partner ID

Valores separados por linha

• Ex.: se o registro de usuário A tiver Partner User ID 1 e identificadores comuns 1, 2 e 3:

identificador comum de usuário 1	p_user_1
identificador comum de usuário 2	p_user_1
identificador comum de usuário 3	p_user_1

*Veja a seção de instruções de hash para identificadores comuns de usuário abaixo

2. Listas de segmentos personalizados

A empresa fornecerá listas de usuários na forma de p_user_id para criar audiências personalizadas para clientes para segmentação na X.

• Valores separados por linha
• p_user_id
• • (O mesmo que fornecido na seção 1. Correspondência completa de dados acima. Se o valor fornecido na correspondência completa de dados estiver com hash, a empresa fornecerá o mesmo valor com hash no arquivo de audiência. Se o valor fornecido não estiver com hash, a empresa fornecerá o valor sem hash.)

​

Requisitos Padrão de Correspondência

Se a empresa não utilizar um id padrão para o mapeamento de todos os identificadores de usuários dos clientes, este é o processo recomendado.

Listas de Segmentos Personalizados

A empresa fornecerá listas de identificadores comuns de usuários com hash diretamente à X, em nome dos clientes, para criar audiências personalizadas.

O formato deste arquivo deve ser:

• Valores separados por linha
• Identificador comum de usuário com hash (por exemplo, endereço de e-mail)
• Seguir as convenções de nomenclatura de arquivos descritas abaixo
• Seguir as instruções de hashing para endereços de e-mail abaixo (em Instruções de Hashing)

​

Nomenclatura e operações de arquivo de List de segmento personalizado

A operação de um arquivo é determinada pelo seu nome, com as seguintes operações disponíveis e a seguinte convenção geral de nomenclatura: audiencename_partnername.handle.operation.filetype

• audiencename: O nome da Custom Audience. Este campo é o nome exibido ao selecionar a audiência na interface de configuração de campanhas em ads.x.com, por exemplo, brand_loyalty_card_holders.
• partnername: Nome da empresa que fornece os data em nome do anunciante, por exemplo, company_name.
• handle: Conta X (@handle) que terá acesso às Custom Audiences, por exemplo, @pepsi, @dietpepsi
• operation: new, add, remove, removeall, replace (detalhes abaixo)
• timestamp: Unix epoch padrão em segundos, usado para garantir que cada arquivo de audiência carregado seja único
• filetype: o arquivo deve estar no formato *.txt

​

Criação e atualização de audiências

Crie uma nova audiência com um único arquivo, por exemplo: loyalty_card_holders_partnername.pepsi.new.txt

Add - Adicione as correspondências de uma lista a uma audiência existente, por exemplo: loyalty_card_holders_partnername.pepsi.add..txt

Remove - Remova as correspondências de uma lista de uma audiência existente. Ex.: loyalty_card_holders_partnername.pepsi.remove..txt

Remove All - Remova, de todas as audiências daquele cliente, as correspondências geradas por uma lista cumulativa atualizada regularmente (ou seja, a Lista de opt-out do cliente). Ex.: partnername.pepsi.removeall.txt

• Isso pode ser usado para uma lista abrangente de usuários que fizeram opt-out do Anunciante.
• A X considerará apenas a lista mais recente fornecida neste arquivo e aplicará isso em todas as audiências existentes e futuras para as correspondências.

Usuários da X no momento em que este arquivo foi fornecido e processado.

Replace - Remova uma audiência existente e substitua-a por uma nova lista de audiência. Ex.: loyalty_card_holders_partnername.pepsi.replace..txt

Opt-out geral da empresa - A empresa fornecerá um arquivo cumulativo de opt-out para remover usuários que fizeram opt-out, de acordo com a política de opt-out da empresa.

A X considerará apenas a lista mais recente fornecida nesse arquivo de opt-out da empresa e aplicará isso em todas as audiências existentes e futuras para os usuários da X correspondentes no momento em que esse arquivo foi fornecido e processado. O formato do arquivo de opt-out da empresa será o seguinte: Ex.: partnername.removeall.txt

Delete - Remova uma audiência existente da lista atual de audiências, por exemplo: loyalty_card_holders_partnername.pepsi.delete.txt

​

Diretrizes de hashing

A X compartilhará com segurança uma chave de produção codificada em base64 via PGP para fazer o hashing de identificadores comuns de usuários (por exemplo, endereços de e‑mail). A empresa decodificará a chave em base64 para obter uma chave de 32 bytes a ser usada no processo de hashing.

Exemplo de chave codificada em base64:

BrQvOg+dACBUmKjRiNxZgJLh6zydjS0ZOv80FelTNzM=

Exemplo de chave decodificada em base64:

/:� TшY

Normalização: A empresa realizará uma normalização básica nos identificadores comuns de usuários antes do hashing (exceto em Device IDs; consulte a seção Device ID Normalization).

​

Normalização de e-mail

Ou seja, remova os espaços no início e no fim e também converta o endereço de e-mail para letras minúsculas.

Ex: Endereço de e-mail original: [e-mail]

Após a normalização: [e-mail]

Valor de hash: 74d9584eded0ad1e5572a1c1849f3716751d371d6117a6155dad5363f4b4fbec

Observação: A quantidade de caracteres tanto do HMAC codificado quanto da chave pode variar conforme a entrada e a codificação, portanto pode haver variação no número de caracteres.

​

Normalização de ID de dispositivo

Aplicaremos os mesmos requisitos para o hash de IDs de dispositivo usando o algoritmo SHA-256 e um salt comum que fornecemos aos parceiros de dados. Removemos espaços, como fazemos com endereços de e‑mail, mas não há normalização para minúsculas para IDFAs/Android IDs, e o formato exato do IDFA/Android ID deve ser utilizado.

A seguir, um exemplo do formato bruto de IDs de dispositivo para iOS e Android, antes do hash:

iOS IDFA: DD99CFF7-6186-4602-9DF2-ED3FD0B2D431

Android ID: b5bf2122961b3595

iOS IDFA com hash: 134fb8cd95c7fd42e2793f469a447198ca5f990968db2dbadad70e723ed9750b

Android ID com hash: 130dddff1939f229476f50bc8adab8fcb7e3525b0e9604fe8effc15e68cee4a4

​

Normalização de ID de usuário do X

Os IDs do X ainda serão submetidos a hashing, pois o agrupamento de data — isto é, Customer List de @handles — é privado para o anunciante, mesmo não sendo PII. Teremos os mesmos requisitos para hashing de IDs do X usando o algoritmo SHA-256 e um salt comum que fornecemos aos parceiros de data. Espaços devem ser removidos tanto do X ID/@username, mas User IDs não requerem normalização. @usernames devem ser convertidos para minúsculas para normalização. E o símbolo @ não deve ser incluído como parte do username.

O formato bruto do ID será:

• User ID: 27674040
• @username: testusername

Hashed User ID: bf6b57d4e861e83bea8bbed2b800b251a64c95468ee6e8cb07c3368c9ed45e85

Hashed @username: 12201ae78ad1afa907c7112d17f498154ffb0bf9ea523f5390e072a06d7d9812

​

Integração de sincronização de ID

Parceiros que enviam data com um p_id devem passar por um processo de sincronização de ID para gerar um mapeamento entre os ids de usuário do anunciante ou parceiro e os ids de usuário do X. Isso permite que os anunciantes segmentem diretamente seus próprios públicos de usuários no X. Os parceiros também devem definir o valor do parâmetro user_identifier_type como TALIST_PARTNER_USER_ID ou TAWEB_PARTNER_USER_ID ao enviar suas atualizações de associação.

• Somente web: Isso pode ser feito inserindo um pixel no site do anunciante, conforme descrito abaixo.
• List: Isso pode ser feito usando qualquer um dos métodos descritos na página CRM.

​

URL do pixel

URL base
https://analytics.x.com/i/adsct

​

Parâmetros do Pixel

Parâmetro	Descrição
p_id	Seu id de parceiro atribuído pela X
p_user_id	O id do usuário no sistema do parceiro

​

Pixel de sincronização de ID:

Usando como exemplo um id de parceiro 111 e um p_user_id abc, o pixel construído seria o seguinte:

    <pre class="brush: xml">
    <img height="1" width="1" src="https://analytics.x.com/i/adsct?p_id=111&p_user_id=abc" style="display:none" />
    </pre>

Configuração de arquivo de opt-out e envio de arquivos de opt-out

Os parceiros devem fornecer à X uma lista de usuários que, segundo o melhor conhecimento do parceiro, optaram por não receber anúncios segmentados. O arquivo deve ter o seguinte formato:

Número da coluna	Nome da coluna	Tipo da coluna	Descrição
1	Partner ID	string	O “partner id” é o ID que a X fornece ao parceiro para identificá-lo de forma exclusiva.
2	id do usuário no sistema do parceiro	string	O p_user_id é o ID exclusivo usado pelo parceiro para identificar o usuário. O arquivo contendo esses usuários de opt-out deve ser carregado usando o endpoint TON upload, e o caminho dos dados enviados deve ser informado ao endpoint Global Opt Out aqui: PUT accounts/:account_id/custom_audiences/global_opt_out.

Envio de atualizações de participação

Conforme especificado na nossa documentação de endpoint, ao enviar usuários pelo endpoint POST custom_audience_memberships, você deve enviar um ID de cliente para permitir uma correspondência baseada em cookies. Parceiros que enviarem dados com um p_id devem definir user_identifier_type como TALIST_PARTNER_USER_ID ou TAWEB_PARTNER_USER_ID.

Todas as outras etapas permanecerão as mesmas das listadas no Guia de Integração da Real-Time Audience API

​

Dados de usuários de Audiências Personalizadas

Este documento descreve o formato dos dados de usuários de [Custom Audience]/x-ads-api/audiences.

Normalização de dados

IDs de dispositivo:

• IDFA — em minúsculas, com hifens; ex.: 4b61639e-47cc-4056-a16a-c8217e029462
• AdID — é necessário o formato original no dispositivo, sem letras maiúsculas e com hifens; ex.: 2f5f5391-3e45-4d02-b645-4575a08f86e
• Android id — é necessário o formato original no dispositivo, sem letras maiúsculas, sem hifens nem espaços; ex.: af3802a465767e36

Endereços de e-mail:

• em minúsculas, remover espaços em branco no início e no fim; ex.: [e-mail]

Nomes de usuário do X:

• sem @, em minúsculas e com espaços em branco no início e no fim removidos; ex.: jack

IDs de usuário do X:

• Número inteiro padrão; ex.: 143567

Hash de dados

Os dados de cada linha devem ser submetidos a hash usando SHA256, sem salt. Além disso, o hash final de saída deve estar em minúsculas. Ex.: 49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d e não 49E0BE2AECCFB51A8DEE4C945C8A70A9AC500CF6F5CB08112575F74DB9B1470D

# fazendo hash do usuário @AdsAPI usando python
import hashlib
hashlib.sha256("adsapi".encode()).hexdigest()

#saída
49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d

Exemplos de código adicionais para hashing podem ser encontrados em github.com/xdevplatform/ads-platform-tools.

​

Públicos personalizados: Web

Informações

Os parceiros enviarão uma lista de IDs (p_user_ids) para veiculação em nome de um anunciante. Isso é feito por meio de um processo de sincronização de ID que cria um mapeamento entre p_user_ids e o id de usuário do X. Esse mapeamento é então usado para gerar listas de IDs de usuário do X que podem ser usadas para segmentação. Esses públicos personalizados ficarão disponíveis no @handle específico do anunciante, conforme indicado pelo rótulo na configuração da campanha Custom Audiences Web em ads.x.com.

A X fornecerá o pixel seguro que pode ser inserido em tags e sites de parceiros para correlacionar os IDs (p_user_ids) aos IDs de usuário do X. Quando o processo de sincronização de ID for concluído, os arquivos de segmentação serão criados pelo parceiro e disponibilizados à X por meio de um endpoint HTTPS. Esses arquivos de segmentação são ingeridos regularmente pela X e, em seguida, disponibilizados na interface da X.

Pixel seguro da X

O pixel seguro da X terá a seguinte aparência:

https://analytics.x.com/i/adsct?p_user_id=xyz&p_id=123

p_user_id - xyz representa o ID de usuário do parceiro fornecido pelo parceiro

p_id - 123 representa o ID exclusivo do parceiro (fornecido pela X)

Endpoint HTTPS do parceiro & arquivo de usuários para segmentação

O parceiro precisará fornecer à X um endpoint HTTPS e credenciais (nome de usuário/senha) que possam ser usadas para ingerir o arquivo de segmentação regularmente. Um endpoint HTTPS de exemplo terá a seguinte aparência:

https://<partnerdomain>/twitter/partner_targeting_%Y-%M-%D.tsv.gz

%Y - Código de formato para ano (YYYY)

%M - Código de formato para mês (MM)

%D - Código de formato para dia (DD)

Os dados transmitidos consistirão nos seguintes arquivos:

1. Partner Targeting User File
2. Targeting Conversion File

Todos os arquivos estarão no formato TSV, em que os campos individuais de cada linha são separados por um caractere de tabulação. Valores válidos de campos nunca conterão o caractere de tabulação.

Faixa de IPs permitida da X:

A seguir está a faixa de IPs que pode ser autorizada para acesso ao Partner endpoint.

• 199.16.156.0/22
• 199.59.148.0/22

Partner Targeting User File:

Número da coluna	Nome da coluna	Tipo da coluna	Descrição
1	partner id	string	O “partner id” é o id que a X fornece ao parceiro para identificar de forma exclusiva cada parceiro.
2	advertiser id	string	O “advertiser id” é o @handle do anunciante.
3	p_user_id	string	O “p_user_id” é o id exclusivo usado pelo parceiro para identificar o usuário.
3	confidence score	integer	O “confidence score” é opcional. Nossa recomendação para confidence score é usar 0–100. Se o caso de uso for retargeting, então um confidence score de “100” indica um usuário que foi diretamente retargeted. Qualquer pontuação de 0–99 corresponderá ao nível de confiança do look‑alike.
4	segment label	string	O “segment label” é opcional. Os parceiros podem usar “segment label” para especificar categorias de produto, por exemplo. Recomendamos usar esse “segment label”, pois é o nome legível por humanos de Custom Audiences na UI do ads.x.com.

Notas:

Sempre que recebermos um novo Partner Targeting File, esperamos que ele seja a lista completa de usuários que o parceiro recomenda segmentar, e não um incremento, a menos que acordado de outra forma. Definiremos com cada parceiro qual será a frequência de entrega desse Partner Targeting File. Se não recebermos um Partner Targeting File conforme esperado, usaremos a versão anterior com um tempo de expiração predefinido.

​

Integração com a Audience API

​

Visão geral

A Audience API foi lançada como parte da v4 da X Ads API e, com isso, traz diversas melhorias em relação aos endpoints legados de Audiences. Este novo endpoint é apoiado por um novo backend de processamento de Audience e oferece melhorias em estabilidade, robustez e confiabilidade. O objetivo deste guia é destacar as diferenças entre a Audience API e os processos legados de upload e gerenciamento de Audience.

A documentação de referência pode ser encontrada na página de referência da Audience API.

Observação: Todos os dados de usuários de Audience devem ser previamente transformados em hash SHA-256 antes do upload. Mais detalhes, juntamente com os tipos de identificadores de usuário aceitos e a normalização de dados, podem ser encontrados na página de user data.

Mudanças na funcionalidade de Audience

As seguintes mudanças em Custom Audiences foram introduzidas a partir da v4, e quaisquer endpoints descontinuados não estarão mais disponíveis após a desativação da v3 da X Ads API:

• Descontinuado Upload TON:
  • GET accounts/:account_id/custom_audience_changes
  • GET accounts/:account_id/custom_audience_changes/:custom_audience_change_id
  • POST accounts/:account_id/custom_audience_changes
  • PUT accounts/:account_id/custom_audiences/global_opt_out
• Descontinuado Real Time Audiences:
  • POST custom_audience_memberships
• Custom Audience:
  • O parâmetro list_type será removido da requisição e da resposta em todos os endpoints de Custom Audience. Esse parâmetro era usado anteriormente para identificar o tipo de identificador de usuário da Audience (isto é, email, X User ID etc.); no entanto, as Audiences agora podem aceitar vários identificadores de usuário para a mesma Audience, tornando esse valor irrelevante.
• Geral:
  • A janela de lookback da Audience foi atualizada para corresponder a usuários ativos nos últimos 90 dias (antes, 30 dias)
  • O número mínimo de usuários correspondidos necessário para que uma audience seja segmentável foi reduzido para 100 usuários (antes, 500 usuários)

Pré-requisitos

• Acesso à X Ads API
• Para acesso ao endpoint de Audience, você precisará ser adicionado a uma allowlist. Preencha este formulário e aceite o novo X Ads Products and Services Agreement se o aceite inicial foi anterior a 2018-08-01

Processo de upload de Audience

A tabela a seguir lista as principais diferenças entre os fluxos antigo e novo de criação de Audience, com mais detalhes disponíveis mais abaixo:

Etapa no processo	Audience API	(Descontinuado) Upload TON
Criar uma Audience shell	Pode ser criada via o [POST custom_audience endpoint]/x-ads-api/audiences	Pode ser criada via o [POST custom_audience endpoint]/x-ads-api/audiences
Adicionar um novo usuário	Use o operation_type Update com o Audience endpoint	Use o operation ADD com o endpoint POST custom_audience_changes
Remover um usuário	Use o operation_type Delete com o Audience endpoint	Use o operation REMOVE com o endpoint POST custom_audience_changes
Opt-out de usuários	Use o operation_type Delete com o Audience endpoint e os respectivos custom_audience_ids dos quais o usuário faz parte	Use o Global opt-out endpoint

Observação Qualquer audience sendo atualizada ou com opt-out pelo caminho de Upload TON deve ter uma lista correspondente enviada via o endpoint TON Upload e associada a uma Audience usando o endpoint custom_audience_changes.

Limitação de taxa

O endpoint da Audience API tem um limite de taxa de 1500/1min por conta. Não há limites para o número de usuários que podem ser enviados em um único payload. As únicas restrições do payload são:

1. Número total de operações: 2500 operações

2. Tamanho máximo do payload: 5.000.000 bytes

Gerenciamento de usuários de Audience

Para criar uma nova Audience, são necessárias as seguintes etapas

​

Criar uma nova Custom Audience

Crie um novo “shell” de Custom Audience usando o endpoint [POST custom_audience]/x-ads-api/audiences e recupere o id correspondente da Custom Audience. Esta etapa é necessária ao criar uma Audience do zero. Se estiver atualizando uma Audience existente, avance para a próxima seção

​

Adicionar usuários a um público

Use POST accounts/:account_id/custom_audiences/:custom_audience_id/users com o id da Custom Audience e um exemplo de payload como o abaixo:

POST https://ads-api.x.com/11/accounts/18ce54d4x5t/custom_audiences/1nmth/users

    # Todos os valores devem ter hash, valores sem hash são usados neste exemplo apenas para fins ilustrativos
    [
      {
        "operation_type": "Update",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "email": [
                "[e-mail]"
              ],
              "handle": [
                "x",
                "adsapi"
              ]
            },
            {
              "email": [
                "[e-mail]"
              ],
              "twitter_id": [
                "121291606",
                "17874544"
              ]
            }
          ]
        }
      }
    ]

Para adicionar um usuário a uma Audiência, use operation_type Update. A nova interface de Audiência permite enviar várias chaves de usuário para um único usuário. Cada objeto no array de objetos JSON corresponde a um único usuário. Usando o payload de exemplo acima, a solicitação adicionará dois usuários a uma Audiência: um com email e handle, e outro com email e twitter_id.

​

Remover usuários de uma audiência

Semelhante ao processo descrito para adicionar usuários, é possível remover usuários de uma audiência da seguinte forma:

POST https://ads-api.x.com/11/accounts/18ce54d4x5t/custom_audiences/1nmth/users

    # Todos os valores devem ser hash, valores sem hash são usados neste exemplo para fins ilustrativos
    [
      {
        "operation_type": "Delete",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "email": [
                "[e-mail]"
              ],
              "twitter_id": [
                "783214",
                "1225933934"
              ]
            },
            {
              "email": [
                "[e-mail]"
              ],
              "twitter_id": [
                "121291606",
                "17874544"
              ]
            }
          ]
        }
      }
    ]

O operation_type deve ser definido como Delete e os usuários serão identificados por quaisquer chaves que estavam presentes quando foram adicionados ao público. Por exemplo, se um usuário foi adicionado a um público usando email e twitter_id, esse mesmo usuário pode ser removido usando qualquer uma dessas chaves, ou seja, email ou twitter_id, ou ambos.

Além disso, é possível adicionar e remover usuários de um público na mesma solicitação. O endpoint oferece suporte a múltiplos operation_type por solicitação.

​

Usuários com opt-out

Com a descontinuação do endpoint global de opt-out, os parceiros devem executar DELETE para quaisquer usuários que tenham optado por sair de quaisquer Audiências. Há algumas maneiras de fazer isso:

1. Acompanhar quais usuários fazem parte de quais Audiências e remover esses usuários individualmente de cada Audiência.
2. Remover o usuário de todas as Audiências associadas a uma conta de Ads.

Práticas recomendadas gerais

• Recomendamos fortemente chamar este endpoint em lotes quase em tempo real para evitar filas com picos, que demoram mais para processar e, em geral, geram carga desnecessária em nosso sistema. Isso também garante que os usuários fiquem disponíveis para segmentação de campanhas mais rapidamente.
• Uma chamada bem-sucedida à API retornará success_count e total_count correspondentes ao número de objetos user recebidos na solicitação.
• Este endpoint é atômico por natureza; ou toda a solicitação é bem-sucedida ou, em caso de qualquer erro, toda a solicitação falhará. Em caso de resposta de erro, recomenda-se que os consumidores da API corrijam o problema e reenviem a solicitação com todo o payload.
• Em caso de falha, recomenda-se que os parceiros usem uma abordagem de exponential backoff com novas tentativas. Por exemplo: tentar novamente imediatamente após a primeira falha, tentar novamente após 1 minuto na segunda falha e tentar novamente após 5 minutos na terceira falha consecutiva, e assim por diante.

​

Referência da API

​

Informações sobre Palavras‑chave

Executar no Postman

​

GET insights/keywords/search

Dado um conjunto de palavras‑chave, obtenha o volume de Tweets associado e um conjunto de 30 palavras‑chave relacionadas. O volume de Tweets corresponde apenas às palavras‑chave informadas, não às relacionadas.

É permitido um intervalo máximo de tempo (end_time - start_time) de 7 dias.

Observação: os resultados são limitados a uma única geo (país).

Resource URL

https://ads-api.x.com/12/insights/keywords/search

Parameters

Name	Description
granularity required	Especifica a granularidade dos dados retornados para o intervalo de tempo definido por start_time e end_time. Por exemplo, quando definido como HOUR, será apresentado um ponto de dado para cada hora entre start_time e end_time. Type: enum Possible values: DAY, HOUR
keywords required	Uma string de palavras‑chave separadas por vírgulas para refinar a pesquisa. Todas as palavras‑chave são combinadas com OR entre si. Note: No máximo 10 palavras‑chave (combinação de keywords e negative_keywords) podem ser usadas. Type: string Example: developers
start_time required	Restringe os dados recuperados ao período entre start_time e end_time. Expresso em ISO 8601. Type: string Example: 2017-07-10T00:00:00Z
end_time optional	Restringe os dados recuperados ao período entre start_time e end_time. Expresso em ISO 8601. Note: O padrão é o horário atual. Type: string Example: 2017-07-11T00:00:00Z
location optional	Um valor de segmentação obtido no endpoint GET targeting_criteria/locations para restringir os resultados conforme a localização do usuário da conta. Observe que, no momento, apenas localizações em nível de país são compatíveis. Type: string Example: 0ce8b9a7b2742f7e
negative_keywords optional	Uma string de palavras‑chave separadas por vírgulas para excluir. Todas as palavras‑chave negativas são combinadas com OR entre si. Note: No máximo 10 palavras‑chave (combinação de keywords e negative_keywords) podem ser usadas. Type: string Example: rain

Example Request

GET https://ads-api.x.com/12/insights/keywords/search?end_time=2018-02-02&granularity=DAY&keywords=developers&start_time=2018-02-01

Exemplo de resposta*

    {
      "request": {
        "params": {
          "start_time": "2018-02-01T00:00:00Z",
          "end_time": "2018-02-02T00:00:00Z",
          "granularity": "DAY",
          "keywords": [
            "developers"
          ]
        }
      },
      "data": {
        "related_keywords": [
          "dev",
          "developer",
          "coders",
          "mysql",
          "devs",
          "#technology",
          "#developers",
          "security",
          "programmers",
          "#tech",
          "javascript",
          "#iot",
          "#bigdata",
          "cloud",
          "devops",
          "php",
          "developer",
          "programmer",
          "engineer",
          "big data",
          "agile",
          "app",
          "programming",
          "ios",
          "maker",
          "startups",
          "developer's",
          "java",
          "#devops",
          "startup"
        ],
        "tweet_volume": [
          15707
        ]
      }
    }

​

Permissões de Audiência Direcionada

Executar no Postman

​

GET accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

Recupera detalhes de algumas ou de todas as permissões associadas à audiência personalizada especificada.

Resource URL

https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

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
tailored_audience_id required	Uma referência à audiência personalizada com a qual você está operando na solicitação. Type: string Example: 1nmth
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
granted_account_ids optional	Restrinja a resposta apenas às contas desejadas especificando uma lista de identificadores separados por vírgulas. Até 200 IDs podem ser fornecidos. Type: string Example: 18ce54aymz3
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
tailored_audience_permission_ids optional	Restrinja a resposta apenas às permissões da audiência personalizada desejadas especificando uma lista de identificadores separados por vírgulas. Até 200 IDs podem ser fornecidos. Type: string Example: ri
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/5/accounts/18ce54d4x5t/tailored_audiences/1nmth/permissions

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "tailored_audience_id": "1nmth"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "tailored_audience_id": "1nmth",
          "permission_level": "READ_ONLY",
          "id": "ri",
          "created_at": "2017-06-08T23:17:59Z",
          "granted_account_id": "18ce54aymz3",
          "updated_at": "2017-06-08T23:17:59Z",
          "deleted": false
        }
      ]
    }

​

POST accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

Cria um novo objeto de permissão que permite compartilhar a audiência especificada com uma determinada conta.

Observação: Criar ou modificar permissões de uma audiência personalizada exige que a audiência pertença à conta que está tentando modificá-las. Você pode verificar a titularidade de uma audiência personalizada consultando o atributo de resposta is_owner na resposta da audiência em questão.

Observação: Audiências só podem ser compartilhadas entre contas de anúncios sob a mesma empresa ou se a conta de anúncios proprietária da audiência tiver o recurso de conta SHARE_AUDIENCE_OUTSIDE_BUSINESS.

Resource URL

https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

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
granted_account_id required	A conta à qual você deseja conceder permissões para a audiência personalizada. Type: string Example: 18ce54aymz3
permission_level required	O tipo de acesso à audiência personalizada que o granted_account_id deve ter. Type: enum Possible values: READ_ONLY, READ_WRITE
tailored_audience_id required	A referência à audiência personalizada com a qual você está operando na solicitação. Type: string Example: 2906h

Example Request

POST https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/2906h/permissions?granted_account_id=18ce54aymz3&permission_level=READ_ONLY

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "granted_account_id": "18ce54aymz3",
          "permission_level": "READ_ONLY",
          "tailored_audience_id": "2906h"
        }
      },
      "data": {
        "tailored_audience_id": "2906h",
        "permission_level": "READ_ONLY",
        "id": "14m",
        "created_at": "2017-09-12T23:49:34Z",
        "granted_account_id": "18ce54aymz3",
        "updated_at": "2017-09-12T23:49:34Z",
        "deleted": false
      }
    }

​

DELETE accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions/:tailored_audience_permission_id

Revoga a permissão de compartilhamento da Tailored Audience especificada.

Observação: Criar ou modificar permissões para uma tailored audience exige que a audiência pertença à conta que está tentando modificar as permissões. Você pode verificar a propriedade de uma tailored audience consultando o atributo de resposta is_owner na resposta para a audiência em questão.

Quando revogada, garantimos que a conta contemplada (granted_account_id) não poderá segmentar a audiência em campanhas futuras. As campanhas existentes continuarão em execução com as audiências compartilhadas; as campanhas não são interrompidas e a audiência não é removida da campanha. Não é possível copiar essa campanha após a revogação da permissão de compartilhamento da audiência.

Resource URL

https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions/:tailored_audience_permission_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
tailored_audience_id required	Referência à tailored audience com a qual você está operando na solicitação. Type: string Example: 1nmth
tailored_audience_permission_id required	Referência à permissão da tailored audience com a qual você está operando na solicitação. Type: string Example: ri

Example Request

DELETE https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/1nmth/permissions/ri

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "tailored_audience_permission_id": "ri",
          "tailored_audience_id": "1nmth"
        }
      },
      "data": {
        "tailored_audience_id": "1nmth",
        "permission_level": "READ_ONLY",
        "id": "ri",
        "created_at": "2017-06-08T23:17:59Z",
        "granted_account_id": "18ce54aymz3",
        "updated_at": "2017-08-30T18:29:35Z",
        "deleted": true
      }
    }

​

Públicos-alvo

Executar no Postman

​

GET accounts/:account_id/custom_audiences/:custom_audience_id/targeted

Recupera uma lista de todos os itens de linha e campanhas, ou apenas os ativos, que segmentam um determinado custom_audience_id.

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 em GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
custom_audience_id required	Referência à audiência personalizada com a qual você está operando na solicitação. Type: string Example: 2906h
with_active optional	Quando false, inclui itens de linha com status servable=false. Type: boolean Default: true Possible values: true, false
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/custom_audiences/2906h/targeted

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_id": "2906h",
        }
      },
      "next_cursor": null,
      "data": [
        {
          "campaign_id": "59hod",
          "campaign_name": "campanha-teste",
          "line_items": [
            {
              "id": "5gzog",
              "name": "test-line-item",
              "servable": true
            }
          ]
        },
        {
          "campaign_id": "arja7",
          "campaign_name": "Campanha sem título",
          "line_items": [
            {
              "id": "bjw1q",
              "name": null,
              "servable": true
            }
          ]
        }
      ]
    }

​

Usuários de Audiências Personalizadas

Executar no Postman

​

POST accounts/:account_id/custom_audiences/:custom_audience_id/users

Este endpoint permite que parceiros adicionem, atualizem e removam usuários de um determinado custom_audience_id. O endpoint também aceita vários tipos de identificadores por usuário.

Todos os dados fornecidos no campo users da solicitação, exceto partner_user_id, devem ser transformados em hash usando SHA256 e normalizados.

Solicitações em lote

• O tamanho máximo atual do lote é 2500 para este endpoint. O tamanho do lote é determinado pelo número de operações (Update/Delete) por solicitação. Por exemplo, mais de 2500 objetos de operação ({"operation_type": "Update/Delete", [..] }) em um único array resultam em erro.
• O tamanho máximo do corpo da solicitação POST que este endpoint pode aceitar é 5,000,000 bytes.
• Os limites de requisições para este endpoint são 1500 por janela de 1 minuto.
• Todos os parâmetros são enviados no corpo da solicitação, e é necessário um Content-Type de 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

A resposta retornada pela X Ads API contém dois campos: success_count e total_count. Esses valores devem sempre ser iguais e representam a contagem de registros na solicitação que foram processados pelo backend. Uma situação em que o número de registros enviados no corpo da solicitação não seja igual a success_count e total_count deve ser tratada como condição de erro, exigindo nova tentativa.

Erros em lote

• Erros no nível da solicitação (por exemplo, tamanho máximo do lote excedido) são exibidos na resposta sob o objeto errors.
• Erros no nível do item (por exemplo, parâmetros obrigatórios ausentes) são exibidos na resposta sob o objeto operation_errors.
• O índice do erro em operation_errors se refere ao índice do item de entrada, com a mensagem de erro correspondente.

​

URL do recurso

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

​

Parâmetros

Nome	Descrição
operation_type obrigatório	O tipo de operação por grupo de users que está sendo executado. Type: enum Valores possíveis: Update, Delete
params obrigatório	Um objeto JSON contendo o array users e os carimbos de data e hora effective_at e expires_at. Type: JSON
users obrigatório	Um array de objetos JSON contendo todos os parâmetros de um usuário individual. Type: JSON
effective_at opcional	O horário em UTC no qual a(s) associação(ões) à audiência personalizada deve(m) entrar em vigor. Expresso em ISO 8601. Padrão: a data e a hora atuais. Type: string Exemplo: 2017-07-05T07:00:00Z
expires_at opcional	O horário em UTC no qual a(s) associação(ões) à audiência personalizada deve(m) expirar. O horário especificado deve ser posterior ao valor de effective_at. Expresso em ISO 8601. Padrão: 13 meses a partir do carimbo de data e hora da solicitação. Type: string Exemplo: 2017-07-05T07:00:00Z

Dada a abordagem de múltiplas chaves para o objeto users, cada elemento desse objeto é documentado abaixo:

Nome	Descrição
email opcional	Endereço(s) de email do usuário. Type: Array[String]
device_id opcional	IDFA/AdID/Android ID Type: Array[String]
handle opcional	O(s) @handle(s) do usuário Type: Array[String]
twitter_id opcional	O ID do X do usuário Type: Array[String]
phone_number opcional	Número(s) de telefone do usuário Type: Array[String]
partner_user_id opcional	O id do usuário no sistema do parceiro. Type: Array[String]

​

Exemplo de solicitação

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/users

    [
      {
        "operation_type": "Update",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "email": [
                "4798b8bbdcf6f2a52e527f46a3d7a7c9aefb541afda03af79c74809ecc6376f3"
              ],
              "handle": [
                "7352f353c460e74c7ae226952d04f8aa307b12329c5512ec8cb6f1a0f8f9b2cb",
                "49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d"
              ]
            },
            {
              "email": [
                "5bf13d5ad4200407c5bc8b9bb578e425d05ef936fd488e3799a9d0806669223c"
              ],
              "twitter_id": [
                "34d56c7159a7eea941f359653029410f813f65a1d2d13ecc5ccbdd5a8cb755cf",
                "00e7b76c9739dec57f4c4a20ec021a20ffcf26bd00f519b17ea00f0ed6048f85"
              ]
            }
          ]
        }
      },
      {
        "operation_type": "Delete",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "device_id": [
                "8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92"
              ],
              "email": [
                "4798b8bbdcf6f2a52e527f46a3d7a7c9aefb541afda03af79c74809ecc6376f3"
              ],
              "handle": [
                "461222f5dd690a20651c3d19848015cb0369db3f8e937571ffb775de70750847"
              ],
              "twitter_id": [
                "c623c7e163984493b46c547088542e95d0aaa529bc52bbecce3ff91eb6b7843b"
              ]
            },
            {
              "email": [
                "5bf13d5ad4200407c5bc8b9bb578e425d05ef936fd488e3799a9d0806669223c"
              ],
              "twitter_id": [
                "858cdc7f313f84a3f3c48e9a6323307c1ef1bb7439b8e3623e140454b0fd8fa5",
                "bb074e154657b91d99bd1bb3757409149670e8ae7a0fe9136fae29a26a7881c8"
              ]
            }
          ]
        }
      }
    ]

​

Exemplo de resposta

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_id": "1nmth"
        }
      },
      "data": {
        "success_count": 4,
        "total_count": 4
      }
    }

​

Permissões de Públicos Personalizados

Executar no Postman

​

GET accounts/:account_id/custom_audiences/:custom_audience_id/permissions

Recupere detalhes de algumas ou todas as permissões associadas à audiência personalizada especificada.

Resource URL

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

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
custom_audience_id required	Uma referência à audiência personalizada com a qual você está operando na solicitação. Type: string Example: 1nmth
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
granted_account_ids optional	Restrinja a resposta apenas às contas desejadas especificando uma lista de identificadores separados por vírgulas. Podem ser fornecidos até 200 IDs. Type: string Example: 18ce54aymz3
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
custom_audience_permission_ids optional	Restrinja a resposta apenas às permissões de audiência personalizada desejadas especificando uma lista de identificadores separados por vírgulas. Podem ser fornecidos até 200 IDs. Type: string Example: ri
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/custom_audiences/1nmth/permissions

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_id": "1nmth"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "custom_audience_id": "1nmth",
          "permission_level": "LEITURA_APENAS",
          "id": "ri",
          "created_at": "2017-06-08T23:17:59Z",
          "granted_account_id": "18ce54aymz3",
          "updated_at": "2017-06-08T23:17:59Z",
          "deleted": false
        }
      ]
    }

​

POST accounts/:account_id/custom_audiences/:custom_audience_id/permissions

Cria um novo objeto de permissão que permite compartilhar a audiência especificada com uma determinada conta.

Observação: Criar ou modificar permissões para uma audiência personalizada exige que a audiência pertença à conta que está tentando modificar as permissões. Você pode verificar a titularidade de uma audiência personalizada consultando o atributo de resposta is_owner na resposta para a audiência em questão.

Observação: Audiências só podem ser compartilhadas entre contas de anúncios do mesmo negócio ou se a conta de anúncios que é proprietária da audiência tiver o recurso de conta SHARE_AUDIENCE_OUTSIDE_BUSINESS.

Resource URL

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

Parameters

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: 18ce54d4x5t
granted_account_id obrigatório	A conta à qual você deseja conceder permissões para a audiência personalizada. Tipo: string Exemplo: 18ce54aymz3
permission_level obrigatório	O tipo de acesso à audiência personalizada que o granted_account_id deve ter. Tipo: enum Valores possíveis: READ_ONLY, READ_WRITE
custom_audience_id obrigatório	Uma referência à audiência personalizada com a qual você está operando na solicitação. Tipo: string Exemplo: 2906h

Exemplo de solicitação

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h/permissions?granted_account_id=18ce54aymz3&permission_level=READ_ONLY

Exemplo de resposta

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "granted_account_id": "18ce54aymz3",
          "permission_level": "READ_ONLY",
          "custom_audience_id": "2906h"
        }
      },
      "data": {
        "custom_audience_id": "2906h",
        "permission_level": "READ_ONLY",
        "id": "14m",
        "created_at": "2017-09-12T23:49:34Z",
        "granted_account_id": "18ce54aymz3",
        "updated_at": "2017-09-12T23:49:34Z",
        "deleted": false
      }
    }

​

DELETE accounts/:account_id/custom_audiences/:custom_audience_id/permissions/:custom_audience_permission_id

Revoga a permissão de compartilhamento da Custom Audience especificada.

Observação: Criar ou modificar permissões para uma custom audience exige que ela seja de propriedade da conta que tenta modificá-las. Você pode verificar a propriedade de uma custom audience consultando o atributo de resposta is_owner na resposta dessa audiência.

Quando revogada, garantimos que a conta autorizada (granted_account_id) não poderá direcionar a audiência em campanhas futuras. As campanhas existentes continuarão em execução com as audiências compartilhadas; as campanhas não param e a audiência não é removida da campanha. Não é possível copiar essa campanha após a revogação da permissão de compartilhamento da audiência.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions/:custom_audience_permission_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
custom_audience_id required	Uma referência à custom audience com a qual você está operando na solicitação. Type: string Example: 1nmth
custom_audience_permission_id required	Uma referência à permissão da custom audience com a qual você está operando na solicitação. Type: string Example: ri

Example Request

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/permissions/ri

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_permission_id": "ri",
          "custom_audience_id": "1nmth"
        }
      },
      "data": {
        "custom_audience_id": "1nmth",
        "permission_level": "READ_ONLY",
        "id": "ri",
        "created_at": "2017-06-08T23:17:59Z",
        "granted_account_id": "18ce54aymz3",
        "updated_at": "2017-08-30T18:29:35Z",
        "deleted": true
      }
    }

​

Públicos personalizados

Executar no Postman

​

GET accounts/:account_id/custom_audiences

Recupera detalhes de algumas ou de todas as Custom Audiences associadas à conta atual.

Resource URL

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

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
permission_scope optional	Permite filtrar a resposta para listas que você possui ou que foram compartilhadas com você. Por padrão, sem especificar este parâmetro, você verá apenas as audiências que possui. Type: enum Default: OWNER Possible values: OWNER, SHARED
q optional	Uma query opcional para restringir o recurso por name. Note: Faz correspondência por prefixo sem diferenciar maiúsculas e minúsculas. 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
custom_audience_ids optional	Restringe a resposta apenas às custom audiences desejadas, especificando uma lista de identificadores separados por vírgula. É possível fornecer até 200 IDs. Type: string Example: 1nmth
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 como 200 por 15 minutos. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences?custom_audience_ids=1nmth

Example Response

    {
      "request": {
        "params": {
          "custom_audience_ids": [
            "1nmth"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "targetable": true,
          "name": "twurl-using-subshell-for-file",
          "targetable_types": [
            "CRM",
            "EXCLUDED_CRM",
          ],
          "audience_type": "CRM",
          "description": null,
          "permission_level": "READ_WRITE",
          "owner_account_id": "18ce54d4x5t",
          "id": "1nmth",
          "reasons_not_targetable": [],
          "created_at": "2017-01-08T08:19:58Z",
          "updated_at": "2017-01-08T16:21:13Z",
          "partner_source": "OTHER",
          "deleted": false,
          "audience_size": 1470
        }
      ]
    }

​

GET accounts/:account_id/custom_audiences/:custom_audience_id

Recupera Audiências Personalizadas específicas associadas à conta atual.

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_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
custom_audience_id obrigatório	Referência à audiência personalizada com a qual você está operando na solicitação. Tipo: string Exemplo: 2906h
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/custom_audiences/2906h

Exemplo de resposta

    {
      "request": {
        "params": {
          "custom_audience_id": "2906h",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "targetable": false,
        "name": "developers",
        "targetable_types": [
          "CRM",
          "EXCLUDED_CRM"
        ],
        "audience_type": "CRM",
        "description": null,
        "permission_level": "READ_WRITE",
        "owner_account_id": "18ce54d4x5t",
        "id": "2906h",
        "reasons_not_targetable": [],
        "created_at": "2017-08-22T23:34:26Z",
        "updated_at": "2017-08-22T23:34:26Z",
        "partner_source": "OTHER"
        "deleted": false,
        "audience_size": 140321
      }
    }

​

POST accounts/:account_id/custom_audiences

Cria um novo Público Personalizado de placeholder associado à conta atual.

Resource URL

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

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 X Ads API, com exceção de GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
name required	O nome de exibição deste público. É obrigatório usar um valor de nome exclusivo; caso contrário, ocorrerá um erro. Type: string Example: ads api users
description optional	Uma descrição para este público. Type: string Example: Collection of all users of the Ads API

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences?name=developers

Example Response

    {
      "data": {
        "targetable": false,
        "name": "developers",
        "targetable_types": [
          "CRM",
          "EXCLUDED_CRM"
        ],
        "audience_type": "CRM",
        "description": null,
        "permission_level": "READ_WRITE",
        "owner_account_id": "18ce54d4x5t",
        "id": "2906h",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "created_at": "2017-08-22T23:34:26Z",
        "updated_at": "2017-08-22T23:34:26Z",
        "partner_source": "OTHER",
        "deleted": false,
        "audience_size": null
      },
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "name": "developers"
        }
      }
    }

​

PUT accounts/:account_id/custom_audiences/:custom_audience_id

Atualize a Custom Audience específica associada à conta atual.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_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 Ads API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
custom_audience_id required	Uma referência à Custom Audience com a qual você está operando na solicitação. Type: string Example: 2906h
name optional	O nome de exibição dessa audiência. Deve ser utilizado um valor de nome exclusivo; caso contrário, ocorrerá um erro. Type: string Example: ads api users
description optional	Uma descrição dessa audiência. Type: string Example: Collection of all users of the Ads API

Example Request

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h?name=developers_changed

Example Response

    {
      "data": {
        "targetable": false,
        "name": "developers_changed",
        "targetable_types": [
          "CRM",
          "EXCLUDED_CRM"
        ],
        "audience_type": "CRM",
        "description": null,
        "permission_level": "READ_WRITE",
        "is_owner": true,
        "id": "2906h",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "created_at": "2017-08-22T23:34:26Z",
        "updated_at": "2017-08-22T23:34:26Z",
        "partner_source": "OTHER",
        "deleted": false,
        "audience_size": null
      },
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "name": "developers_changed"
        }
      }
    }

​

POST batch/accounts/:account_id/custom_audiences

Permite a criação em lote de Custom Audiences. Consulte a página Visão geral de Custom Audiences para obter informações sobre audiências.

Observação: Este endpoint de lote está atualmente em beta fechado e disponível para anunciantes selecionados. Durante este período de beta, somente Flexible Audiences baseadas em mobile custom audiences podem ser criadas.

Batch Requests

• O tamanho máximo atual do lote é 10.
• Todos os parâmetros são enviados no corpo da requisição e é necessá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.

Batch Responses

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

Batch Errors

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

Flexible Audiences

Executar no Postman

• Flexible Audiences são imutáveis após serem criadas.
• Custom Audiences são fornecidas em uma estrutura em árvore com combinações de lógica booleana para criar Flexible Audiences.
• No máximo 10 nós folha de Custom Audiences podem ser usados para criar uma Flexible Audience.

Resource URL

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

Parameters

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
audience_type obrigatório	O tipo de audiência a ser criada. Type: enum Possible values: FLEXIBLE, MOBILE_AUDIENCE
child_segments obrigatório	Um array contendo objetos que definem o subconjunto dos membros de uma Custom Audience que você deseja segmentar. Cada objeto deve conter um custom_audience_id, frequency, frequency_comparator, lookback_window, negate e, em alguns casos, child_segments adicionais. Type: array
name obrigatório	O nome de exibição da audiência. Um valor de nome exclusivo deve ser usado. Caso contrário, ocorrerá um erro. Type: string Example: my_flexible_audience_name
operation_type obrigatório	O tipo de operação por item que está sendo executada. Type: enum Possible values: Create, Update, Delete
boolean_operator às vezes obrigatório	A relação lógica entre os segmentos filhos no objeto pai (contêiner). Obrigatório se child_segments não estiver vazio para o objeto pai. Type: enum Possible values: AND, OR
lookback_window às vezes obrigatório	Um valor inteiro que especifica o intervalo de dias dentro do qual o usuário realizou a ação específica e se qualificou para a custom audience em questão. Type: int Possible values: 1, 7, 14, 30
segments às vezes obrigatório	Um objeto contendo um boolean_operator e child_segments que definem o subconjunto dos membros de uma Custom Audience que você deseja segmentar. Type: object
custom_audience_id às vezes obrigatório	O id da custom audience a ser usada como segmento filho. Type: string Example: tyfo
frequency opcional	Um valor inteiro que especifica a frequência, dentro da lookback window, com que o usuário realizou a ação específica e se qualificou para a custom audience em questão. Type: int Default value: 1
frequency_comparator opcional	O comparador do frequency enviado na solicitação. Observação: Nos valores abaixo, GTE refere-se a maior ou igual, LT a menor que, e assim por diante. Type: string Possible values: NUM_GTE, NUM_GT, NUM_EQ, NUM_LTE, NUM_LT Default value: NUM_GTE
negate opcional	Nega o segmento e, assim, ele é excluído da combinação. Type: boolean Default value: true Possible values: true, false

Exemplo de solicitação

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

    [
      {
        "operation_type":"Create",
        "params":{
          "name":"my_flexible_audience_name",
          "audience_type":"FLEXIBLE",
          "segments":{
            "boolean_operator":"AND",
            "child_segments":[
              {
                "custom_audience_id":"TYIF",
                "frequency":1,
                "frequency_comparator":"NUM_GT",
                "lookback_window":30,
                "negate":true,
                "child_segments":[

                ]
              },
              {
                "boolean_operator":"OR",
                "child_segments":[
                  {
                    "custom_audience_id":"TXR1",
                    "lookback_window":30,
                    "child_segments":[

                    ]
                  },
                  {
                    "custom_audience_id":"TYFO",
                    "frequency":1,
                    "frequency_comparator":"NUM_GT",
                    "lookback_window":30,
                    "negate":true,
                    "child_segments":[

                    ]
                  }
                ]
              }
            ]
          }
        }
      }
    ]

Exemplo de resposta

    {
      "data": {
        "targetable": false,
        "name": "meu_nome_de_público_flexível",
        "targetable_types": [
          "FLEXIBLE",
          "EXCLUDED_FLEXIBLE"
        ],
        "audience_type": "FLEXIBLE",
        "id": "13ld7",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "metadata": [
          {
            "custom_audience_id": "13ld7",
            "account_id": "qsx3w2",
            "name": "meu_nome_de_público_flexível",
            "audience_source": "FLEXIBLE_AUDIENCE",
            "upload_status": "UPLOADED",
            "segments": {
              "boolean_operator": "AND",
              "frequency": 1,
              "frequency_comparator": "NUM_GTE",
              "negate": false,
              "child_segments": [
                {
                  "custom_audience_id": "tyif",
                  "lookback_window": 30,
                  "frequency": 1,
                  "frequency_comparator": "NUM_GT",
                  "negate": true,
                  "child_segments": [

                  ]
                },
                {
                  "boolean_operator": "OR",
                  "frequency": 1,
                  "frequency_comparator": "NUM_GTE",
                  "negate": false,
                  "child_segments": [
                    {
                      "custom_audience_id": "txr1",
                      "lookback_window": 30,
                      "frequency": 1,
                      "frequency_comparator": "NUM_GTE",
                      "negate": false,
                      "child_segments": [

                      ]
                    },
                    {
                      "custom_audience_id": "tyfo",
                      "lookback_window": 30,
                      "frequency": 1,
                      "frequency_comparator": "NUM_GT",
                      "negate": true,
                      "child_segments": [

                      ]
                    }
                  ]
                }
              ]
            }
          }
        ],
        "created_at": "2015-11-10T21:26:43Z",
        "updated_at": "2015-11-11T01:11:47Z",
        "partner_source": "OTHER",
        "deleted": false,
        "audience_size": null
      },
      "request": [
        {
          "params": {
            "name": "meu_nome_de_público_flexível",
            "audience_type": "FLEXIBLE",
            "segments": {
              "boolean_operator": "AND",
              "child_segments": [
                {
                  "custom_audience_id": "TYIF",
                  "lookback_window": 30,
                  "frequency": 1,
                  "frequency_comparator": "NUM_GT",
                  "negate": true,
                  "child_segments": [

                  ]
                },
                {
                  "boolean_operator": "OR",
                  "child_segments": [
                    {
                      "custom_audience_id": "TXR1",
                      "lookback_window": 30,
                      "child_segments": [

                      ]
                    },
                    {
                      "custom_audience_id": "TYFO",
                      "lookback_window": 30,
                      "frequency": 1,
                      "frequency_comparator": "NUM_GT",
                      "negate": true,
                      "child_segments": [

                      ]
                    }
                  ]
                }
              ]
            },
            "account_id": "qsx3w2"
          },
          "operation_type": "Create"
        }
      ]
    }

​

DELETE accounts/:account_id/custom_audiences/:custom_audience_id

Exclui a Custom Audience especificada pertencente à conta atual.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_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
custom_audience_id required	Uma referência à Custom Audience com a qual você está operando na solicitação. Type: string Example: 2906h

Example Request

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h

Example Response

    {
      "data": {
        "targetable": false,
        "name": "developers",
        "targetable_types": [
          "CRM",
          "EXCLUDED_CRM"
        ],
        "audience_type": "CRM",
        "description": null,
        "permission_level": "READ_WRITE",
        "owner_account_id": "18ce54d4x5t",
        "id": "2906h",
        "reasons_not_targetable": [
          "TOO_SMALL"
        ],
        "created_at": "2017-08-22T23:34:26Z",
        "updated_at": "2017-08-30T18:09:00Z",
        "partner_source": "OTHER",
        "deleted": true,
        "audience_size": null
      },
      "request": {
        "params": {
          "custom_audience_id": "2906h",
          "account_id": "18ce54d4x5t"
        }
      }
    }

​

Listas de Não Contatar

Executar no Postman

​

GET accounts/:account_id/do_not_reach_lists

Recupere detalhes de uma ou de todas as Do Not Reach List associadas à conta atual.

Observação: Um account_id pode ter no máximo uma Do Not Reach List

Resource URL

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

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
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/18ce54bgxky/do_not_reach_lists

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54bgxky"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "targetable": false,
          "name": "Lista de Não Alcançar",
          "description": "teste DNRL",
          "id": "4kzrq",
          "reasons_not_targetable": [
            "PEQUENO_DEMAIS"
          ],
          "created_at": "2021-10-28T22:09:29Z",
          "list_size": null,
          "updated_at": "2021-11-04T03:33:06Z",
          "deleted": false
        }
      ]
    }

​

POST accounts/:account_id/do_not_reach_lists

Cria uma nova Do Not Reach List associada à conta atual.

Observação: Um account_id pode ter no máximo uma Do Not Reach List

Resource URL

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

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
description optional	Uma descrição para esse público. Type: string Example: A list of users to exclude

Example Request

POST https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists?description=A list of users to exclude

Example Response

    {
      "request": {
        "params": {
          "description": "Uma lista de usuários a serem excluídos",
          "account_id": "18ce54bgxky"
        }
      },
      "data": {
        "targetable": false,
        "name": "Lista de Não Alvo",
        "description": "Uma lista de usuários a serem excluídos"
        "id": "4ofrq",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "created_at": "2022-02-08T23:02:48Z",
        "list_size": null,
        "updated_at": "2022-02-08T23:02:48Z",
        "deleted": false
      }
    }

​

POST batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users

Este endpoint permite adicionar, atualizar e remover usuários de um determinado do_not_reach_list_id. Este endpoint aceita apenas e-mails como tipo válido de identificador de usuário.

Todos os dados fornecidos no campo emails da solicitação devem ser transformados em hash usando SHA256 e normalizados.

Observações

• Um account_id pode ter no máximo uma Do Not Reach List
• Usuários adicionados a esta lista devem ter um carimbo de data/hora expires_at definido para menos de 13 meses a partir do carimbo de data/hora atual
• A API de Do Not Reach List não aceita um carimbo de data/hora effective_at e usa por padrão o carimbo de data/hora atual
• A Do Not Reach List não remove usuários de quaisquer audiências personalizadas da conta, mas atua como exclusão de segmentação para todas as campanhas veiculadas para a conta

Solicitações em lote

• O tamanho máximo atual do lote é 2500 para este endpoint. O tamanho do lote é determinado pelo número de operações (Update/Delete) por solicitação. Por exemplo, mais de 2500 objetos de operação ({"operation_type": "Update/Delete", [..] }) em um único array resultam em erro.
• O tamanho máximo do corpo da solicitação POST que este endpoint pode aceitar é de 5,000,000 bytes.
• Os limites de requisições para este endpoint são 1500 por janela de 1 minuto
• Todos os parâmetros são enviados no corpo da solicitação e é necessário um Content-Type de application/json.
• Solicitações em lote falham ou são bem-sucedidas em conjunto 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

A resposta retornada pela X Ads API contém dois campos: success_count e total_count. Esses valores devem sempre ser iguais e representam a contagem de registros na solicitação que foram processados pelo backend. Uma situação em que o número de registros enviados no corpo da solicitação não seja igual a success_count e total_count deve ser tratada como condição de erro, exigindo nova tentativa.

Erros em lote

• Erros no nível da solicitação (por exemplo, tamanho máximo do lote excedido) são exibidos na resposta no objeto errors.
• Erros no nível do item (por exemplo, parâmetros obrigatórios ausentes) são exibidos na resposta no objeto operation_errors.
• O índice do erro em operation_errors refere-se ao índice no item de entrada, com a correspondente mensagem de erro

Resource URL

https://ads-api.x.com/12/batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/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 Ads API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
do_not_reach_list_id required	Uma referência à Do Not Reach List com a qual você está operando na solicitação Type: string Example: 2906h
operation_type required	O tipo de operação por grupo users que está sendo executada. Type: enum Possible values: Update, Delete
params required	Um objeto JSON contendo o array emails e o carimbo de data/hora expires_at. Type: JSON
users required	Um array de objetos JSON contendo todos os parâmetros de um usuário individual. Type: JSON
expires_at optional	A hora em UTC na qual a(s) associação(ões) do usuário deve(m) expirar. A hora especificada deve ser posterior ao valor do carimbo de data/hora atual. Expressa em ISO 8601. O padrão é 13 meses a partir do carimbo de data/hora atual. Type: string Example: 2017-07-05T07:00:00Z

Dada a abordagem de várias chaves para o objeto users, cada elemento desse objeto está documentado abaixo:

Nome	Descrição
email opcional	Endereço(s) de e-mail do usuário. type: Array[String]
phone_number opcional	Número(s) de telefone do usuário. type: Array[String]

Exemplo de solicitação

`POST https://ads-api.x.com/12/batch/accounts/18ce54bgxky/do_not_reach_lists/4kzro/users`

    [
      {
        "operation_type": "Update",
        "params": {
          "expires_at": "2023-01-22T00:00:00Z",
          "users": [
            {
              "email": [
                "FEAD76F6ADF99FFFB997AA4E3C8AD38FF531BC4C956DBD03CD0163F744D8AABC"
              ],
              "phone_number": [
                "CCABF1B62A202E0FE28BC6C014983C89A65451DD4482BD66A0ADB65366F38A9A"
              ]
            },
            {
              "email": [
                "FEAD76F6ADF99FFFB997AA4E3C8AD38FF531BC4C956DBD03CD0163F744D8AABA"
              ],
              "phone_number": [
                "CCABF1B62A202E0FE28BC6C014983C89A65451DD4482BD66A0ADB65366F38A9E"
              ]
            }
          ]
        }
      }
    ]

Exemplo de resposta

    {
      "data": [
        {
          "success_count": 2,
          "total_count": 2
        }
      ],
      "request": [
        {
          "params": {
            "do_not_reach_list_id": "4ofrq",
            "expires_at": "2023-01-22T00:00:00Z",
            "account_id": "18ce54bgxky"
          },
          "operation_type": "Update"
        }
      ]
    }

​

DELETE accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id

Exclui a Do Not Reach List especificada pertencente à conta atual.

URL do recurso

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

Parâmetros

Nenhum

Exemplo de solicitação

DELETE https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists/4ofrp

Exemplo de resposta

    {
      "request": {
        "params": {
          "do_not_reach_list_id": "4ofrp",
          "account_id": "18ce54bgxky"
        }
      },
      "data": {
        "targetable": false,
        "name": "Lista de Não Contatar",
        "description": null,
        "id": "4ofrp",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "created_at": "2022-02-08T23:02:07Z",
        "list_size": null,
        "updated_at": "2022-02-08T23:02:21Z",
        "deleted": true
      }
    }