LeadGo
Criar conta
Páginas da documentação

Desenvolvedores · Referência · v1.2.0

Leads

Leads dos formulários instantâneos e o funil comercial: listar, consultar, mudar a etapa, registrar venda e perda, notas e exclusão (LGPD).

https://leadgo.com.br/api/v1 Baixar arquivo para IA OpenAPI 3.1 Criar token
GET /leads leads:read

Listar leads

Leads dos formulários instantâneos, dos mais novos para os mais antigos, com as respostas, a nota da IA e a campanha de origem. Pagine com cursor (meta.next_cursor). Para manter um CRM em dia, prefira os webhooks lead.created, lead.scored e lead.status_changed e use esta rota para a carga inicial ou para conferir. Dados pessoais: guarde só o que precisar.

Parâmetros

status string new, contacted, qualified, won, lost ou spam.
campaign_id string Só os leads de uma campanha.
score string Nota da IA: hot, warm ou cold.
received_from string Recebidos a partir deste dia (AAAA-MM-DD, no fuso da conta).
received_to string Recebidos até este dia, inclusive (AAAA-MM-DD).
search string Nome, e-mail ou parte do telefone (4 dígitos ou mais).
limit integer Itens por página, de 1 a 100 (padrão 25).
cursor string meta.next_cursor da página anterior.

Exemplo

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

Resposta 200

HTTP 200 
{
    "data": [
        {
            "id": "01jbz2k8m4q0t6w2y8b4e0h6na",
            "platform_lead_id": "1234567890123456",
            "name": "Mariana Lima",
            "email": "[email protected]",
            "phone": "+5511987654321",
            "answers": {
                "Qual o melhor horário para contato?": "Depois das 18h",
                "Qual produto você procura?": "Kit verão"
            },
            "status": "new",
            "status_label": "Novo",
            "value_cents": null,
            "lost_reason": null,
            "score": "hot",
            "score_label": "Quente",
            "score_reason": "Respondeu o produto e o horário; quer comprar já.",
            "suggested_message": "Oi, Mariana! Vi que você procura o Kit verão. Posso te mandar as opções depois das 18h?",
            "whatsapp_url": "https://wa.me/5511987654321?text=Oi%2C%20Mariana%21",
            "campaign": {
                "id": "01jby0q4c8m2d6t9v3k7w5r1xa",
                "name": "Cadastro kit verão"
            },
            "ad_set": {
                "id": 88,
                "name": "Mulheres 25-45 SP"
            },
            "ad": {
                "id": 140,
                "name": "Anúncio 1"
            },
            "form_id": "987654321098765",
            "received_at": "2026-10-28T14:20:00+00:00",
            "first_contact_at": null,
            "qualified_at": null,
            "won_at": null,
            "scored_at": "2026-10-28T14:20:09+00:00",
            "links": {
                "panel": "https://app.leadgo.com.br/app/leads/01jbz2k8m4q0t6w2y8b4e0h6na"
            }
        }
    ],
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": "https://app.leadgo.com.br/api/v1/leads?cursor=eyJpZCI6..."
    },
    "meta": {
        "path": "https://app.leadgo.com.br/api/v1/leads",
        "per_page": 25,
        "next_cursor": "eyJpZCI6...",
        "prev_cursor": null
    }
}

Erros: validation_failed

GET /leads/stats leads:read

Indicadores do funil

Os mesmos números da central de leads do painel no período: leads (sem spam), qualificados, vendas, faturamento em centavos, taxa de qualificação (%), minutos até o primeiro contato e custo por qualificado (na moeda da conta, com o gasto das campanhas de origem).

Parâmetros

days integer 7, 30 (padrão), 90 ou 0 (todo o período).

Exemplo

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

Resposta 200

HTTP 200 
{
    "data": {
        "days": 30,
        "today": 4,
        "total": 182,
        "qualified": 61,
        "won": 23,
        "revenue_cents": 1873400,
        "qualification_rate": 41.2,
        "avg_first_contact_minutes": 37,
        "cost_per_qualified": 18.4,
        "currency": "BRL"
    }
}

Erros: validation_failed

GET /leads/{id} leads:read

Consultar lead

Um lead com o histórico (events, do mais novo ao mais antigo): recebido, nota da IA, mudanças de etapa, notas, contatos e envios ao CRM e à Meta.

Exemplo

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

Resposta 200

HTTP 200 
{
    "data": {
        "id": "01jbz2k8m4q0t6w2y8b4e0h6na",
        "platform_lead_id": "1234567890123456",
        "name": "Mariana Lima",
        "email": "[email protected]",
        "phone": "+5511987654321",
        "answers": {
            "Qual o melhor horário para contato?": "Depois das 18h",
            "Qual produto você procura?": "Kit verão"
        },
        "status": "won",
        "status_label": "Vendeu",
        "value_cents": 25900,
        "lost_reason": null,
        "score": "hot",
        "score_label": "Quente",
        "score_reason": "Respondeu o produto e o horário; quer comprar já.",
        "suggested_message": "Oi, Mariana! Vi que você procura o Kit verão. Posso te mandar as opções depois das 18h?",
        "whatsapp_url": "https://wa.me/5511987654321?text=Oi%2C%20Mariana%21",
        "campaign": {
            "id": "01jby0q4c8m2d6t9v3k7w5r1xa",
            "name": "Cadastro kit verão"
        },
        "ad_set": {
            "id": 88,
            "name": "Mulheres 25-45 SP"
        },
        "ad": {
            "id": 140,
            "name": "Anúncio 1"
        },
        "form_id": "987654321098765",
        "received_at": "2026-10-28T14:20:00+00:00",
        "first_contact_at": "2026-10-28T14:35:00+00:00",
        "qualified_at": "2026-10-28T16:00:00+00:00",
        "won_at": "2026-10-28T16:00:00+00:00",
        "scored_at": "2026-10-28T14:20:09+00:00",
        "events": [
            {
                "id": 902,
                "type": "status_changed",
                "label": "Status alterado",
                "data": {
                    "from": "contacted",
                    "to": "won",
                    "value_cents": 25900
                },
                "user": {
                    "id": 42,
                    "name": "Ana Souza"
                },
                "created_at": "2026-10-28T16:00:00+00:00"
            },
            {
                "id": 901,
                "type": "scored",
                "label": "Qualificado pela IA",
                "data": {
                    "score": "hot"
                },
                "user": null,
                "created_at": "2026-10-28T14:20:09+00:00"
            },
            {
                "id": 900,
                "type": "received",
                "label": "Lead recebido",
                "data": null,
                "user": null,
                "created_at": "2026-10-28T14:20:01+00:00"
            }
        ],
        "links": {
            "panel": "https://app.leadgo.com.br/app/leads/01jbz2k8m4q0t6w2y8b4e0h6na"
        }
    }
}

Erros: not_found

PATCH /leads/{id} leads:write

Mudar a etapa do lead

Move o lead no funil, como no painel. A mudança entra no histórico, dispara o webhook lead.status_changed e, nos planos com inteligência de leads, manda a qualificação e a venda para a Meta (a Meta passa a buscar mais gente parecida com quem compra). Venda (won) pode levar o valor; perda (lost), o motivo.

Corpo

status obrigatório string new, contacted, qualified, won, lost ou spam.
value_cents integer Só com won: valor da venda em centavos (maior que zero).
lost_reason string Só com lost: motivo (até 255 caracteres).

Exemplo

cURL 
curl -X PATCH "https://leadgo.com.br/api/v1/leads/{id}" \
  -H "Authorization: Bearer $LEADGO_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "won",
    "value_cents": 25900
}'

Resposta 200

HTTP 200 
{
    "data": {
        "id": "01jbz2k8m4q0t6w2y8b4e0h6na",
        "platform_lead_id": "1234567890123456",
        "name": "Mariana Lima",
        "email": "[email protected]",
        "phone": "+5511987654321",
        "answers": {
            "Qual o melhor horário para contato?": "Depois das 18h",
            "Qual produto você procura?": "Kit verão"
        },
        "status": "won",
        "status_label": "Vendeu",
        "value_cents": 25900,
        "lost_reason": null,
        "score": "hot",
        "score_label": "Quente",
        "score_reason": "Respondeu o produto e o horário; quer comprar já.",
        "suggested_message": "Oi, Mariana! Vi que você procura o Kit verão. Posso te mandar as opções depois das 18h?",
        "whatsapp_url": "https://wa.me/5511987654321?text=Oi%2C%20Mariana%21",
        "campaign": {
            "id": "01jby0q4c8m2d6t9v3k7w5r1xa",
            "name": "Cadastro kit verão"
        },
        "ad_set": {
            "id": 88,
            "name": "Mulheres 25-45 SP"
        },
        "ad": {
            "id": 140,
            "name": "Anúncio 1"
        },
        "form_id": "987654321098765",
        "received_at": "2026-10-28T14:20:00+00:00",
        "first_contact_at": "2026-10-28T14:35:00+00:00",
        "qualified_at": "2026-10-28T16:00:00+00:00",
        "won_at": "2026-10-28T16:00:00+00:00",
        "scored_at": "2026-10-28T14:20:09+00:00",
        "events": [
            {
                "id": 902,
                "type": "status_changed",
                "label": "Status alterado",
                "data": {
                    "from": "contacted",
                    "to": "won",
                    "value_cents": 25900
                },
                "user": {
                    "id": 42,
                    "name": "Ana Souza"
                },
                "created_at": "2026-10-28T16:00:00+00:00"
            },
            {
                "id": 901,
                "type": "scored",
                "label": "Qualificado pela IA",
                "data": {
                    "score": "hot"
                },
                "user": null,
                "created_at": "2026-10-28T14:20:09+00:00"
            },
            {
                "id": 900,
                "type": "received",
                "label": "Lead recebido",
                "data": null,
                "user": null,
                "created_at": "2026-10-28T14:20:01+00:00"
            }
        ],
        "links": {
            "panel": "https://app.leadgo.com.br/app/leads/01jbz2k8m4q0t6w2y8b4e0h6na"
        }
    }
}

Erros: validation_failed, not_found

POST /leads/{id}/contacted leads:write

Registrar contato

O vendedor falou com o lead: grava o primeiro contato (que entra no tempo médio de resposta) e, se o lead ainda era new, passa para contacted.

Exemplo

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

Resposta 200

HTTP 200 
{
    "data": {
        "id": "01jbz2k8m4q0t6w2y8b4e0h6na",
        "platform_lead_id": "1234567890123456",
        "name": "Mariana Lima",
        "email": "[email protected]",
        "phone": "+5511987654321",
        "answers": {
            "Qual o melhor horário para contato?": "Depois das 18h",
            "Qual produto você procura?": "Kit verão"
        },
        "status": "contacted",
        "status_label": "Contatado",
        "value_cents": null,
        "lost_reason": null,
        "score": "hot",
        "score_label": "Quente",
        "score_reason": "Respondeu o produto e o horário; quer comprar já.",
        "suggested_message": "Oi, Mariana! Vi que você procura o Kit verão. Posso te mandar as opções depois das 18h?",
        "whatsapp_url": "https://wa.me/5511987654321?text=Oi%2C%20Mariana%21",
        "campaign": {
            "id": "01jby0q4c8m2d6t9v3k7w5r1xa",
            "name": "Cadastro kit verão"
        },
        "ad_set": {
            "id": 88,
            "name": "Mulheres 25-45 SP"
        },
        "ad": {
            "id": 140,
            "name": "Anúncio 1"
        },
        "form_id": "987654321098765",
        "received_at": "2026-10-28T14:20:00+00:00",
        "first_contact_at": "2026-10-28T14:35:00+00:00",
        "qualified_at": null,
        "won_at": null,
        "scored_at": "2026-10-28T14:20:09+00:00",
        "links": {
            "panel": "https://app.leadgo.com.br/app/leads/01jbz2k8m4q0t6w2y8b4e0h6na"
        }
    }
}

Erros: not_found

POST /leads/{id}/notes leads:write

Adicionar nota

Uma anotação no histórico do lead, em nome de quem criou o token.

Corpo

text obrigatório string Até 2000 caracteres.

Exemplo

cURL 
curl -X POST "https://leadgo.com.br/api/v1/leads/{id}/notes" \
  -H "Authorization: Bearer $LEADGO_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Pediu orçamento do kit com 3 peças. Retornar na sexta."
}'

Resposta 201

HTTP 201 
{
    "data": {
        "id": "01jbz2k8m4q0t6w2y8b4e0h6na",
        "platform_lead_id": "1234567890123456",
        "name": "Mariana Lima",
        "email": "[email protected]",
        "phone": "+5511987654321",
        "answers": {
            "Qual o melhor horário para contato?": "Depois das 18h",
            "Qual produto você procura?": "Kit verão"
        },
        "status": "contacted",
        "status_label": "Contatado",
        "value_cents": null,
        "lost_reason": null,
        "score": "hot",
        "score_label": "Quente",
        "score_reason": "Respondeu o produto e o horário; quer comprar já.",
        "suggested_message": "Oi, Mariana! Vi que você procura o Kit verão. Posso te mandar as opções depois das 18h?",
        "whatsapp_url": "https://wa.me/5511987654321?text=Oi%2C%20Mariana%21",
        "campaign": {
            "id": "01jby0q4c8m2d6t9v3k7w5r1xa",
            "name": "Cadastro kit verão"
        },
        "ad_set": {
            "id": 88,
            "name": "Mulheres 25-45 SP"
        },
        "ad": {
            "id": 140,
            "name": "Anúncio 1"
        },
        "form_id": "987654321098765",
        "received_at": "2026-10-28T14:20:00+00:00",
        "first_contact_at": "2026-10-28T14:35:00+00:00",
        "qualified_at": null,
        "won_at": null,
        "scored_at": "2026-10-28T14:20:09+00:00",
        "events": [
            {
                "id": 902,
                "type": "status_changed",
                "label": "Status alterado",
                "data": {
                    "from": "contacted",
                    "to": "won",
                    "value_cents": 25900
                },
                "user": {
                    "id": 42,
                    "name": "Ana Souza"
                },
                "created_at": "2026-10-28T16:00:00+00:00"
            },
            {
                "id": 901,
                "type": "scored",
                "label": "Qualificado pela IA",
                "data": {
                    "score": "hot"
                },
                "user": null,
                "created_at": "2026-10-28T14:20:09+00:00"
            },
            {
                "id": 900,
                "type": "received",
                "label": "Lead recebido",
                "data": null,
                "user": null,
                "created_at": "2026-10-28T14:20:01+00:00"
            }
        ],
        "links": {
            "panel": "https://app.leadgo.com.br/app/leads/01jbz2k8m4q0t6w2y8b4e0h6na"
        }
    }
}

Erros: validation_failed, not_found

DELETE /leads/{id} leads:write

Excluir lead (LGPD)

Apaga de vez o lead e o histórico, para atender ao pedido do titular dos dados. Não apaga na Meta: os leads ficam lá por 90 dias, conforme a política deles.

Exemplo

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

Resposta 204

Sem corpo.

Erros: not_found