Públicos — Referência da API

GET /audiences campaigns:read

Listar públicos

Os públicos da conta de anúncio: os do sistema (source system: compradores e o semelhante a eles), os de remarketing criados pela API ou pelo painel (source user) e os que já existiam na Meta (source imported, trazidos por POST /audiences/sync e todo dia). Use o platform_audience_id em targeting.audience_id (incluir) ou targeting.excluded_audience_ids (deixar de fora).

Parâmetros

type	string	customer_list, lookalike, website ou meta_engagement.
source	string	system, user ou imported.

Exemplo

cURL

curl -X GET "https://leadgo.com.br/api/v1/audiences" \
  -H "Authorization: Bearer $LEADGO_TOKEN" \
  -H "Accept: application/json"

Resposta 200

HTTP 200

{
    "data": [
        {
            "id": 17,
            "platform_audience_id": "23859876543210987",
            "name": "Visitantes do site — 30 dias",
            "description": null,
            "type": "website",
            "type_label": "Visitantes do site",
            "source": "user",
            "purpose": null,
            "status": "ready",
            "rule": {
                "pixel_id": "123456789012345",
                "retention_days": 30,
                "url_contains": "/produtos"
            },
            "country": null,
            "approximate_size": 4800,
            "can_delete": true,
            "last_synced_at": "2026-10-28T15:00:00+00:00",
            "created_at": "2026-10-28T15:00:00+00:00"
        },
        {
            "id": 3,
            "platform_audience_id": "23851234567890123",
            "name": "Compradores",
            "description": null,
            "type": "customer_list",
            "type_label": "Lista de clientes",
            "source": "system",
            "purpose": "buyers",
            "status": null,
            "rule": null,
            "country": null,
            "approximate_size": 1200,
            "can_delete": false,
            "last_synced_at": "2026-10-28T03:00:00+00:00",
            "created_at": "2026-10-01T03:00:00+00:00"
        }
    ]
}

Erros: validation_failed, ad_account_not_linked

GET /audiences/{id} campaigns:read

Consultar público

Um público pelo id. approximate_size e status são os da última sincronização (a Meta leva algumas horas para encher um público novo e só entrega anúncios para ele a partir de cerca de 100 pessoas).

Exemplo

cURL

curl -X GET "https://leadgo.com.br/api/v1/audiences/{id}" \
  -H "Authorization: Bearer $LEADGO_TOKEN" \
  -H "Accept: application/json"

Resposta 200

HTTP 200

{
    "data": {
        "id": 17,
        "platform_audience_id": "23859876543210987",
        "name": "Visitantes do site — 30 dias",
        "description": null,
        "type": "website",
        "type_label": "Visitantes do site",
        "source": "user",
        "purpose": null,
        "status": "ready",
        "rule": {
            "pixel_id": "123456789012345",
            "retention_days": 30,
            "url_contains": "/produtos"
        },
        "country": null,
        "approximate_size": 4800,
        "can_delete": true,
        "last_synced_at": "2026-10-28T15:00:00+00:00",
        "created_at": "2026-10-28T15:00:00+00:00"
    }
}

Erros: not_found

POST /audiences campaigns:write

Criar público de remarketing

Cria na Meta um público de quem visitou o site (type website, pelo Pixel) ou de quem interagiu com a Página ou o perfil do Instagram (type meta_engagement). A pessoa fica no público pelos dias de retention_days depois da última visita ou interação. Gasta a cota de consultas à plataforma.

Corpo

type obrigatório	string	website ou meta_engagement.
name obrigatório	string	Nome do público (até 120 caracteres).
description	string	Para você lembrar do que se trata (até 500).
retention_days obrigatório	integer	Dias para trás: até 180 no website e até 365 no engajamento.
pixel_id	string	website: o Pixel (GET /ad-account/pixels). Obrigatório nesse tipo.
url_contains	string	website: só quem visitou páginas cujo endereço contém esse trecho (ex.: /produtos). Em branco, qualquer página.
engagement_source	string	meta_engagement: page (Página do Facebook) ou instagram. Obrigatório nesse tipo.
source_id	string	meta_engagement: id da Página ou do perfil do Instagram (GET /ad-account/instagram-accounts). Em branco com page, vale a Página da conexão; com instagram é obrigatório.

Exemplo

cURL

curl -X POST "https://leadgo.com.br/api/v1/audiences" \
  -H "Authorization: Bearer $LEADGO_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "website",
    "name": "Visitantes do site — 30 dias",
    "retention_days": 30,
    "pixel_id": "123456789012345",
    "url_contains": "/produtos"
}'

Resposta 201

HTTP 201

{
    "data": {
        "id": 17,
        "platform_audience_id": "23859876543210987",
        "name": "Visitantes do site — 30 dias",
        "description": null,
        "type": "website",
        "type_label": "Visitantes do site",
        "source": "user",
        "purpose": null,
        "status": "ready",
        "rule": {
            "pixel_id": "123456789012345",
            "retention_days": 30,
            "url_contains": "/produtos"
        },
        "country": null,
        "approximate_size": 4800,
        "can_delete": true,
        "last_synced_at": "2026-10-28T15:00:00+00:00",
        "created_at": "2026-10-28T15:00:00+00:00"
    }
}

Erros: validation_failed, ad_account_not_linked, operation_failed, platform_quota_exceeded, platform_rejected, platform_unavailable

DELETE /audiences/{id} campaigns:write

Excluir público

Exclui o público na Meta e aqui. Só os que têm can_delete true: os do sistema são mantidos pelas vendas dos leads, e os criados direto na Meta se excluem pelo Gerenciador de Anúncios. Campanhas que usavam o público perdem essa parte da segmentação.

Exemplo

cURL

curl -X DELETE "https://leadgo.com.br/api/v1/audiences/{id}" \
  -H "Authorization: Bearer $LEADGO_TOKEN" \
  -H "Accept: application/json"

Resposta 204

Sem corpo.

Erros: not_found, audience_not_deletable, platform_quota_exceeded, platform_rejected

POST /audiences/sync campaigns:write

Sincronizar públicos com a Meta

Traz na hora a lista da conta de anúncio: os criados direto na Meta entram como imported, os conhecidos atualizam tamanho e situação, e os que sumiram de lá saem daqui. As rotinas já fazem isso todo dia; aqui, no máximo uma vez por minuto.

Exemplo

cURL

curl -X POST "https://leadgo.com.br/api/v1/audiences/sync" \
  -H "Authorization: Bearer $LEADGO_TOKEN" \
  -H "Accept: application/json"

Resposta 200

HTTP 200

{
    "data": {
        "created": 2,
        "updated": 5,
        "removed": 0
    }
}

Erros: ad_account_not_linked, sync_too_soon, operation_failed, platform_quota_exceeded, platform_unavailable