Imagine que um novo contato chegou (por um formulário, uma indicação, uma conversa em evento) e você quer que ele entre na esteira de prospecção agora, sem ninguém digitar nada na plataforma.

É exatamente isso que esta página resolve. Com uma única chamada você faz duas coisas ao mesmo tempo:

1. Cria o lead (a pessoa/empresa que você vai prospectar).
2. Coloca esse lead em uma cadência — o nome que o GS Engage dá para a sequência de atividades de contato (ligar, mandar e-mail, mandar WhatsApp) que o vendedor segue.

Se a cadência tiver a distribuição automática ligada — ou se você indicar um responsável na própria chamada — a prospecção começa na hora e a primeira atividade já aparece para o vendedor.

Você vai precisar de duas coisas:

Você tem dois caminhos, escolha o que for mais confortável:

curl "https://api.gsengage.com/api/v1/routines?apiKey=SUA_CHAVE"

{
  "data": [
    {
      "id": "665f1a2b3c4d5e6f7a8b9c0d",
      "name": "Outbound - SDR Time A",
      "status": "ACTIVE"
    }
  ],
  "meta": { "limit": 20, "count": 1, "total": 1, "page": 1, "totalPages": 1 }
}

Os dados do lead vão no corpo (body) da requisição, em formato JSON. A regra de ouro:

Os contatos ficam em três listas, e cada item tem sempre o mesmo formato — um value (o dado) e um label (um rótulo livre, ex.: "Trabalho", "Pessoal"):

Este é o gatilho: enviamos um POST para o caminho da cadência com os dados do lead no corpo. Escolha sua linguagem.

curl -X POST "https://api.gsengage.com/api/v1/routines/665f1a2b3c4d5e6f7a8b9c0d/lead?apiKey=SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "fullName": "Maria Silva",
    "emails": [
      { "value": "maria@empresa.com", "label": "Trabalho" }
    ],
    "mobiles": [
      { "value": "+5511999998888", "label": "WhatsApp" }
    ]
  }'

const apiKey = process.env.GSENGAGE_API_KEY; // guarde a chave em variável de ambiente
const routineId = "665f1a2b3c4d5e6f7a8b9c0d";

const res = await fetch(
  `https://api.gsengage.com/api/v1/routines/${routineId}/lead?apiKey=${apiKey}`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      fullName: "Maria Silva",
      emails: [{ value: "maria@empresa.com", label: "Trabalho" }],
      mobiles: [{ value: "+5511999998888", label: "WhatsApp" }],
    }),
  }
);

const lead = await res.json();
console.log(res.status, lead);

import os
import requests

api_key = os.environ["GSENGAGE_API_KEY"]  # guarde a chave em variável de ambiente
routine_id = "665f1a2b3c4d5e6f7a8b9c0d"

resp = requests.post(
    f"https://api.gsengage.com/api/v1/routines/{routine_id}/lead",
    params={"apiKey": api_key},
    json={
        "fullName": "Maria Silva",
        "emails": [{"value": "maria@empresa.com", "label": "Trabalho"}],
        "mobiles": [{"value": "+5511999998888", "label": "WhatsApp"}],
    },
)

print(resp.status_code, resp.json())

Quando tudo funciona, a API responde com HTTP 201 Created e devolve o lead recém-criado (com o id dele). Na prática, isso significa:

• O lead foi cadastrado no seu projeto.
• Ele entrou marcado como Levantada de Mão — o rótulo do GS Engage para o contato que chega já demonstrando interesse. Por isso ele aparece no topo da fila de atividades do vendedor.
• Se a cadência tem distribuição automática ligada (ou você passou um responsável), a prospecção já começou e a primeira atividade está pronta para o time trabalhar.

graph LR
A["POST /routines/{routineId}/lead"] --> B["Lead criado (Levantada de Mão)"]
B --> C{"Distribuição automática ativa<br/>ou responsibleId informado?"}
C -->|"Sim"| D["Prospecção iniciada<br/>1ª atividade na fila"]
C -->|"Não"| E["Lead na cadência,<br/>aguardando distribuição"]

Este endpoint é para o caso "pessoa nova, quero criar e já prospectar". Se o lead já está cadastrado e você só quer colocá-lo em uma cadência, use outro caminho:

Um exemplo de prospecção para lead existente:

{
  "leadId": "665fabc0123456789abcdef0",
  "routineId": "665f1a2b3c4d5e6f7a8b9c0d",
  "responsibleId": "665f9876543210fedcba0000"
}

Quando algo não dá certo, a API responde com um código de erro e uma mensagem em português, já pronta para você reaproveitar. Os dois casos mais frequentes:

400 — Lead sem contato

Você tentou criar o lead sem nenhum e-mail, telefone ou celular. O corpo do erro aponta o campo:

{
  "error": {
    "message": "Não foi possível criar o lead.",
    "errors": [
      { "field": ["emails"], "message": "Informe ao menos um contato (e-mail, telefone ou celular)." }
    ]
  }
}

O que houve: o lead veio sem forma de contato. Por quê: pelo menos um contato é obrigatório. Como corrigir: adicione um item em emails, phones ou mobiles e reenvie.

404 — Cadência não encontrada

O routineId no caminho não corresponde a nenhuma cadência do projeto:

{
  "error": {
    "message": "Cadência não encontrada."
  }
}

O que houve: a API não achou essa cadência. Por quê: o routineId está errado, incompleto ou é de outro projeto. Como corrigir: confirme o routineId com GET /api/v1/routines (veja acima) e cheque se a apiKey é do projeto certo.