# Adicionar um lead e iniciar uma cadência

> Cadastre um novo lead direto em uma cadência e comece a prospecção na mesma chamada, sem passos manuais.

- URL canônica: https://docs.growthstation.app/docs/api/guias/adicionar-lead-cadencia
- Idioma: pt-BR
- Última atualização: 2026-09-20T08:21:20.450Z
- Produto: GS Engage
- Mantido por: Produto GS Engage



<PageHero emoji="🚀" title="Adicionar um lead e iniciar uma cadência" description="O fluxo mais comum da API: você cadastra a pessoa e já coloca ela na fila do vendedor." gradient="brand" />

🎯 O que você quer alcançar [#-o-que-você-quer-alcançar]

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.

<Callout type="tip" title="Em uma frase">
  Uma chamada = lead criado + lead na cadência + (se possível) prospecção iniciada.
</Callout>

🧭 Antes de começar [#-antes-de-começar]

Você vai precisar de duas coisas:

<FieldInfoGroup>
  <FieldInfo title="Sua apiKey" required>
    A chave de API do projeto, criada em <TextHighlight>Configurações > Configurações de API</TextHighlight>. Ela vai na URL como <code>?apiKey=SUA\_CHAVE</code>. Veja o [Quickstart](/docs/api/comece-aqui/quickstart) se ainda não tiver a sua.
  </FieldInfo>

  <FieldInfo title="O routineId da cadência" required>
    O identificador da cadência onde o lead vai entrar. É o <code>{'{routineId}'}</code> que aparece no caminho do endpoint. Como obter está logo abaixo.
  </FieldInfo>
</FieldInfoGroup>

<Callout type="warning" title="Toda chamada é real">
  Não existe ambiente de teste (sandbox) separado. Cadastrar um lead por aqui **cria um registro de verdade** no seu projeto e pode disparar atividades para o vendedor. Ao experimentar, comece por leituras (GET) e só faça a escrita quando estiver seguro.
</Callout>

🔑 Como descobrir o routineId [#-como-descobrir-o-routineid]

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

<Tabs items={['Pela API (GET /routines)', 'Copiando do app']}>
  <Tab value="Pela API (GET /routines)">
    Liste as cadências do projeto e pegue o `id` da que você quer. É uma leitura, então é seguro rodar à vontade.

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

    A resposta traz uma lista paginada. Cada item tem um `id` (o seu `routineId`) e um `name` para você confirmar que é a cadência certa:

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

    Copie o valor de `id`.
  </Tab>

  <Tab value="Copiando do app">
    Abra a cadência dentro do GS Engage. O `routineId` aparece no endereço (URL) da página da cadência — é a sequência longa de letras e números. Copie ela e use no lugar de `{routineId}`.
  </Tab>
</Tabs>

<Callout type="info" title="O que é esse código comprido?">
  O `routineId` (e os outros `id` da API) é um identificador único de 24 caracteres. Você não precisa entender o formato — só copiar e colar exatamente como veio.
</Callout>

📝 Montando o corpo do lead [#-montando-o-corpo-do-lead]

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

<Callout type="warning" title="Todo lead precisa de pelo menos um contato">
  Um lead **não pode** ser criado sem forma de contato. Você precisa informar **pelo menos um** item em `emails`, `phones` ou `mobiles`.
</Callout>

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"):

| Campo      | O que é                  | Exemplo de item                                         |
| ---------- | ------------------------ | ------------------------------------------------------- |
| `fullName` | Nome completo do lead    | `"Maria Silva"`                                         |
| `emails`   | Lista de e-mails         | `{ "value": "maria@empresa.com", "label": "Trabalho" }` |
| `phones`   | Lista de telefones fixos | `{ "value": "+551133334444", "label": "Comercial" }`    |
| `mobiles`  | Lista de celulares       | `{ "value": "+5511999998888", "label": "WhatsApp" }`    |

🚀 Fazendo a chamada [#-fazendo-a-chamada]

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

<Tabs items={['cURL', 'Node.js', 'Python']}>
  <Tab value="cURL">
    ```bash
    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" }
        ]
      }'
    ```
  </Tab>

  <Tab value="Node.js">
    ```js
    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);
    ```
  </Tab>

  <Tab value="Python">
    ```python
    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())
    ```
  </Tab>
</Tabs>

<Callout type="danger" title="Sua apiKey é uma senha">
  Como a chave vai na **URL**, ela aparece em logs de servidor, no histórico do navegador e em qualquer link compartilhado. Nunca cole a URL completa em chat público, ticket ou print. Guarde a chave em uma **variável de ambiente**, como nos exemplos de Node e Python.
</Callout>

✅ Deu certo: o retorno 201 [#-deu-certo-o-retorno-201]

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.

<Mermaid
  chart={`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"]`}
/>

<Callout type="tip" title="Quer confirmar depois?">
  Você pode listar as prospecções desse lead com `GET /api/v1/prospections?leadId=ID_DO_LEAD` para ver se a esteira começou. Veja [Consultar prospecções](/docs/api/guias/extrair-para-dashboard).
</Callout>

🔀 E se o lead já existe? [#-e-se-o-lead-já-existe]

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:

<Callout type="info" title="Lead novo vs. lead que já existe">
  **`POST /api/v1/routines/{routineId}/lead`** → cria o lead **e** inicia a prospecção. Use quando o contato ainda não existe.

  **`POST /api/v1/prospections`** → inicia a prospecção de um lead **que já existe**. Você informa `leadId`, `routineId` e, opcionalmente, `responsibleId`.
</Callout>

Um exemplo de prospecção para lead existente:

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

<DoDont>
  <DoDontItem type="do">
    Use 

    `POST /routines/{routineId}/lead`

     quando o contato acabou de chegar e ainda não está na base.
  </DoDontItem>

  <DoDontItem type="do">
    Use 

    `POST /prospections`

     para um lead que você já criou antes (e tem o 

    `leadId`

    ).
  </DoDontItem>

  <DoDontItem type="dont">
    Não cadastre o mesmo lead duas vezes só para colocá-lo em outra cadência — isso gera duplicidade.
  </DoDontItem>
</DoDont>

🩹 Erros mais comuns [#-erros-mais-comuns]

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 [#400--lead-sem-contato]

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

```json
{
  "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 [#404--cadência-não-encontrada]

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

```json
{
  "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.

<Callout type="info" title="Outros retornos que valem conhecer">
  **401** — a `apiKey` está ausente ou inválida. **429** — você passou do limite de requisições (100 escritas por minuto); respeite o header `Retry-After` e tente de novo. Detalhes em [Erros e limites](/docs/api/conceitos/respostas-e-erros).
</Callout>

🧾 Checklist rápido [#-checklist-rápido]

<Checklist id="adicionar-lead-cadencia" title="Antes de disparar em produção">
  <ChecklistItem>
    Peguei o 

    `routineId`

     certo (via 

    `GET /api/v1/routines`

     ou pelo app)?
  </ChecklistItem>

  <ChecklistItem>
    O corpo tem pelo menos um contato em 

    `emails`

    , 

    `phones`

     ou 

    `mobiles`

    ?
  </ChecklistItem>

  <ChecklistItem>
    A 

    `apiKey`

     está em variável de ambiente, e não colada em canal público?
  </ChecklistItem>

  <ChecklistItem>
    Sei se a cadência tem distribuição automática — ou passei um responsável — para a prospecção começar na hora?
  </ChecklistItem>

  <ChecklistItem>
    Confirmei a criação pelo retorno 

    **201**

     (e, se quiser, por 

    `GET /api/v1/prospections?leadId=...`

    )?
  </ChecklistItem>
</Checklist>

❓ Perguntas frequentes [#-perguntas-frequentes]

<FAQ>
  <FAQItem question="A prospecção sempre começa sozinha ao criar o lead?">
    Não. Ela começa automaticamente quando a cadência tem a **distribuição automática** ligada, ou quando você indica um responsável na chamada. Sem nenhum dos dois, o lead entra na cadência e fica aguardando distribuição.
  </FAQItem>

  <FAQItem question="Preciso criar o lead antes com POST /api/v1/leads?">
    Não para este fluxo. O `POST /api/v1/routines/{routineId}/lead` já cria o lead. O endpoint `POST /api/v1/leads` serve para cadastrar um lead **sem** colocá-lo direto em uma cadência.
  </FAQItem>

  <FAQItem question="Por que meu lead apareceu no topo da fila do vendedor?">
    Porque todo lead criado pela API entra marcado como **Levantada de Mão** — o rótulo de quem chega demonstrando interesse. Esses leads têm prioridade na fila de atividades.
  </FAQItem>

  <FAQItem question="Consigo fazer isso sem programar?">
    Sim. O GS Engage tem gatilhos nativos no **Zapier**, e ferramentas como **Make** e **n8n** também conseguem chamar esta API REST — dá para montar o fluxo sem escrever código.
  </FAQItem>
</FAQ>

Artigos Relacionados [#artigos-relacionados]

<RelatedArticles>
  <RelatedArticle href="/docs/api/comece-aqui/quickstart" title="Quickstart da API" description="Crie sua apiKey e faça a primeira chamada em minutos." />

  <RelatedArticle href="/docs/api/guias/extrair-para-dashboard" title="Consultar prospecções" description="Acompanhe as esteiras que já começaram." />

  <RelatedArticle href="/docs/api/conceitos/respostas-e-erros" title="Erros e limites" description="Entenda 400, 401, 404 e o rate limit da API." />

  <RelatedArticle href="/docs/api/referencia" title="Referência de Leads" description="Todos os campos e contatos de um lead." />
</RelatedArticles>