Listas e segmentação — Referência da API

GET /reference campaigns:read

Valores aceitos

Objetivos (e o que cada um exige: link, Pixel, vídeo, WhatsApp), botões, países, eventos de conversão, categorias especiais, campos de formulário, tipos de mídia, limites, escopos e eventos de webhook. Os mesmos do painel. Em limits, max_url_tags conta os parâmetros de URL extras, na campanha e no anúncio: os 4 UTMs padrão (utm_source, utm_medium, utm_campaign e utm_content) ficam fora da conta.

Exemplo

cURL

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

Resposta 200

HTTP 200

{
    "data": {
        "goals": [
            {
                "value": "traffic",
                "label": "Tráfego",
                "description": "Leva pessoas para o seu site, loja ou WhatsApp.",
                "needs_link": true,
                "requires_pixel": false,
                "requires_video": false,
                "uses_messaging": false
            }
        ],
        "call_to_actions": [
            {
                "value": "LEARN_MORE",
                "label": "Saiba mais"
            }
        ],
        "countries": [
            {
                "value": "BR",
                "label": "Brasil"
            }
        ],
        "conversion_events": [
            {
                "value": "PURCHASE",
                "label": "Compra"
            }
        ],
        "limits": {
            "max_creatives": 10,
            "max_cities": 25,
            "max_interests": 25,
            "max_interest_groups": 3,
            "max_url_tags": 10
        }
    }
}

GET /targeting/cities campaigns:read

Buscar cidades

Cidades da segmentação da Meta. Use key e name em targeting.cities. Resultados ficam em cache por um dia; buscas novas gastam a cota de consultas à plataforma.

Parâmetros

q obrigatório	string	Nome da cidade (mínimo 2 letras).
country	string	Restringe a um país (BR, AR...).

Exemplo

cURL

curl -X GET "https://leadgo.com.br/api/v1/targeting/cities?q=Campinas&country=BR" \
  -H "Authorization: Bearer $LEADGO_TOKEN" \
  -H "Accept: application/json"

Resposta 200

HTTP 200

{
    "data": [
        {
            "key": "2490299",
            "name": "Campinas, São Paulo",
            "type": "Cidade",
            "detail": "São Paulo, Brasil",
            "country_code": "BR"
        }
    ]
}

Erros: validation_failed, platform_quota_exceeded, ad_account_not_linked

GET /targeting/interests campaigns:read

Buscar interesses

Interesses da segmentação da Meta. Use id e name em targeting.interests (ou num grupo de targeting.narrow_interests).

Parâmetros

q obrigatório

string

Termo (mínimo 2 letras).

Exemplo

cURL

curl -X GET "https://leadgo.com.br/api/v1/targeting/interests?q=corrida" \
  -H "Authorization: Bearer $LEADGO_TOKEN" \
  -H "Accept: application/json"

Resposta 200

HTTP 200

{
    "data": [
        {
            "id": "6003397425735",
            "name": "Corrida",
            "audience_size": 48000000
        }
    ]
}

Erros: validation_failed, platform_quota_exceeded, ad_account_not_linked

POST /targeting/reach-estimate campaigns:read

Estimar alcance

Quantas pessoas cabem num público, segundo a Meta, antes de criar a campanha. Recebe o mesmo persona_id e o mesmo objeto targeting de POST /campaigns (com exclusões, idiomas e grupos de interesses). Quando a Meta ainda está calculando, ready vem false: tente de novo em instantes. Com targeting.narrow_interests, cada grupo é estimado à parte (uma consulta à plataforma por grupo): narrowed vem true, upper é o teto do menor grupo e lower vem null (o cruzamento a Meta só calcula depois de publicar). warning traz um aviso quando o público pode ser pequeno demais para a Meta entregar (senão, null). Cache de 1 hora para a mesma segmentação.

Corpo

persona_id	integer	Persona da conta como base do público.
targeting	object	O mesmo objeto targeting de POST /campaigns.

Exemplo

cURL

curl -X POST "https://leadgo.com.br/api/v1/targeting/reach-estimate" \
  -H "Authorization: Bearer $LEADGO_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "targeting": {
        "cities": [
            {
                "key": "269969",
                "name": "São Paulo, São Paulo",
                "country_code": "BR",
                "radius_km": 25
            }
        ],
        "age_min": 25,
        "age_max": 45,
        "gender": "female",
        "interests": [
            {
                "id": "6003107902433",
                "name": "Compras online"
            }
        ]
    }
}'

Resposta 200

HTTP 200

{
    "data": {
        "available": true,
        "lower": 1200000,
        "upper": 1450000,
        "ready": true,
        "narrowed": false,
        "warning": null
    }
}

Erros: validation_failed, ad_account_not_linked, platform_quota_exceeded, platform_unavailable