Ads

Listar públicos do Meta Ads e listas de usuários do Google Ads pela API

Uma rota lista os públicos personalizados da conta de anúncios do cliente, com id, nome, tipo e tamanho aproximado. O id vai na segmentação do conjunto de anúncios, e você lê tudo pela conexão do cliente, sem implementar OAuth nem passar pelo app review da Meta.

A chamada

GET /api/ads/audiences?customer_integration=<connection uuid>
Authorization: Bearer <merchant token>
x-customer-token: <customer token>

O que dá para fazer

  • Listar os públicos personalizados da conta com GET /ads/audiences.
  • Usar o id de cada público em targeting.custom_audiences ao criar um conjunto de anúncios.
  • Ver o nome, o subtype e o tamanho aproximado (approximate_size, de lower a upper) de cada público.
  • Forçar uma leitura nova da plataforma com refresh=true.
  • No Google Ads, listar as listas de usuários abertas da conta (remarketing e customer match) com a mesma rota.

Regras e limites

  • A rota é só de leitura. Criar públicos e enviar listas de usuários não faz parte desta versão.
  • Não é paginada: vêm no máximo 200 itens por leitura.
  • Cache de 600 s por conexão. meta.cached e meta.cached_at mostram se veio do cache, e refresh=true ignora.
  • A conexão vai sempre em ?customer_integration= e a chamada exige Authorization e x-customer-token.
  • No Google Ads, o Google dá um tamanho aproximado só, que vem em lower e em upper.
  • No Google Ads, os resultados ainda não entram na criação: campanha e grupo nascem sem segmentação de local, idioma ou público.

Campos principais

CampoTipoObrigatórioDescrição
customer_integrationstringSimuuid da conexão do cliente. Define a conta de anúncios. Vai sempre na query.
refreshbooleanNãoIgnora o cache de 600 s e busca de novo na plataforma.
idstringNãoNa resposta: o id do público. É o que vai em targeting.custom_audiences.
namestringNãoNa resposta: o nome do público na conta.
subtypestringNãoNa resposta: o tipo do público na plataforma.
approximate_sizeobjectNãoNa resposta: o tamanho aproximado, como faixa com lower e upper.

Para quem

  • Seletor de público no seu SaaS

    Mostre ao cliente os públicos que ele já tem na conta e deixe escolher quais usar no conjunto de anúncios.

  • Remarketing por agência

    Uma agência lista os públicos de visitantes do cliente e cria um conjunto de anúncios direcionado a eles.

  • Agente de IA que monta campanhas

    Um agente lê os públicos da conta, escolhe o de clientes atuais e o usa na segmentação do novo conjunto.

Funciona com

  • Meta Ads
  • Google Ads

Perguntas frequentes

Posso criar um público personalizado pela API?

Ainda não. A rota é só de leitura: criar públicos e enviar listas de usuários não fazem parte desta versão.

Onde uso o id do público?

Em targeting.custom_audiences, na segmentação do conjunto de anúncios.

Um público novo aparece na hora?

A leitura tem cache de 600 s por conexão. Use refresh=true para buscar de novo na plataforma.

Relacionadas

Ver tudo que dá para fazer em Ads

Veja o Connect aplicado ao seu produto.

Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.