Primeira chamada

Aqui você faz a primeira conversa de verdade com a API: confirma que a chave funciona, cria um lead e vê o que acontece quando o mesmo lead chega duas vezes. Antes, crie a sua chave em Chaves de API.

Os exemplos usam dados inventados

Maria Souza, o e-mail maria@exemplo.com.br, o telefone e os códigos (UUIDs) dos exemplos são fictícios. As respostas seguem o formato da referência da API. Na sua conta, os códigos e as datas serão outros.

O que é o curl

O curl é um programa que envia uma chamada para um endereço da internet e mostra a resposta. Vem pronto no Mac e no Linux.

No Windows, abra o PowerShell ou o Terminal e use curl.exe (com o .exe). Sem o .exe, o PowerShell chama outro comando que não é o curl.

Nos exemplos abaixo, a barra invertida \ no fim da linha só serve para quebrar o comando em várias linhas. No Mac e no Linux, copie e cole do jeito que está. No PowerShell do Windows, a quebra de linha é o acento grave `; mais simples é juntar tudo em uma linha só, sem as barras.

Aspas no PowerShell do Windows

No PowerShell, as aspas duplas dentro do -d '...' costumam se perder e a API responde validation_error (“O corpo precisa ser um JSON válido.”). O jeito mais seguro é salvar o JSON em um arquivo, por exemplo lead.json, e usar -d "@lead.json" no lugar do -d '...'. Para criar o arquivo, abra o Bloco de Notas, cole o JSON e salve como lead.json com a codificação UTF-8, na mesma pasta em que o PowerShell está aberto (ou use o caminho completo, como -d "@C:\Users\voce\lead.json").

Nunca coloque a chave no endereço

A chave vai só no cabeçalho Authorization. Se crm_live_ aparecer no endereço (URL), a API recusa a chamada com o erro api_key_in_url, mesmo que o cabeçalho esteja certo. Endereços ficam guardados em históricos e registros, então a chave não pode ir ali.

Em todos os exemplos, troque crm_live_SUA_CHAVE_AQUI pela chave que você copiou do CRM.

Passo 1: testar a chave com GET /me

O GET /me não mexe em nada. Ele só responde de quem é a chave. É o melhor primeiro teste.

curl https://dattacrm.com.br/api/v1/me \
  -H "Authorization: Bearer crm_live_SUA_CHAVE_AQUI"

Se tudo estiver certo, a resposta é parecida com esta:

{
  "data": {
    "organization": {
      "id": "3f6c2a9e-0000-4000-8000-000000000001",
      "name": "Minha Agência",
      "slug": "minha-agencia"
    },
    "apiKey": {
      "id": "3f6c2a9e-0000-4000-8000-000000000002",
      "name": "n8n",
      "prefix": "crm_live_xxxx",
      "expiresAt": "2027-01-18T13:00:00.000Z"
    }
  }
}

O que cada parte diz:

• organization: a conta do CRM dona da chave. Confira se o nome é o da conta certa.
• apiKey: a chave usada. O prefix é o início dela, o mesmo que aparece na tela Integrações › API. O expiresAt é quando ela vence, ou null se ela não vence.

Se vier um erro em vez disso, veja Erros comuns. O mais frequente aqui é invalid_api_key: a chave foi colada com algum erro ou a palavra Bearer ficou de fora.

Passo 2: criar um lead com POST /leads

O POST /leads cria um lead. Ele exige pelo menos e-mail ou telefone. Criar um lead também exige uma lista: use listId (o id da lista, que você copia em Leads). A chave não tem lista, então a lista vai sempre na chamada; sem ela, a API responde 400 com list_required. Aqui vamos mandar nome, e-mail, telefone, a lista e duas tags.

curl -X POST https://dattacrm.com.br/api/v1/leads \
  -H "Authorization: Bearer crm_live_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Souza",
    "email": "maria@exemplo.com.br",
    "phone": "+55 11 90000-0000",
    "listId": "ID_DA_SUA_LISTA",
    "tags": ["lead-api", "teste"]
  }'

As tags são os nomes das tags. O telefone pode ter máscara ou +55; se não tiver o código do país, vale o país padrão da conta.

A resposta traz "result": "created" no fim, que quer dizer que o lead foi criado (o status HTTP é 201; veja no Passo 3 como exibi-lo):

{
  "data": {
    "lead": {
      "id": "3f6c2a9e-0000-4000-8000-000000000010",
      "name": "Maria Souza",
      "email": "maria@exemplo.com.br",
      "phone": "+55 11 90000-0000",
      "tags": ["lead-api", "teste"],
      "listIds": ["3f6c2a9e-0000-4000-8000-000000000020"],
      "ownerId": null,
      "customFields": {},
      "origin": "site",
      "source": "Site",
      "lists": [
        {
          "listId": "3f6c2a9e-0000-4000-8000-000000000020",
          "listName": "Inscritos",
          "folderId": "3f6c2a9e-0000-4000-8000-000000000030",
          "folderName": "Lançamento",
          "origin": "site",
          "stageId": null,
          "stageName": null,
          "stageKind": null,
          "stageEnteredAt": null,
          "value": 0,
          "lossReasonId": null
        }
      ],
      "utm": {
        "source": null,
        "medium": null,
        "campaign": null,
        "term": null,
        "content": null
      },
      "createdAt": "2026-10-20T13:00:00.000Z",
      "updatedAt": "2026-10-20T13:00:00.000Z",
      "url": "https://dattacrm.com.br/leads/3f6c2a9e-0000-4000-8000-000000000010"
    },
    "result": "created"
  }
}

Alguns pontos para reparar:

• result: “created” diz que o lead é novo.
• origin é a chave da origem do lead (site, whatsapp ou instagram) e source é o rótulo dela (“Site”, “WhatsApp” ou “Instagram”). Quem manda é a lista de destino: a origem de um lead novo é a da lista escolhida e não muda depois. Se você mandar source na chamada, ele é ignorado.
• lists traz as listas do lead, cada uma com id, name e origin.
• listId: a lista de destino do lead (ou listIds, e a primeira vale como destino). É obrigatório para criar um lead: a chave de API não tem lista, então, sem listId nem listIds, a resposta é 400 list_required. Um lead que já existe continua sendo atualizado sem lista.
• url: abre a ficha do lead no CRM. Guarde o id: ele é o código que você usa para alterar esse lead depois.

Passo 3: mandar de novo e ver o matched

Rode o mesmo comando outra vez. Desta vez a resposta volta com "result": "matched" no fim, e o lead é o mesmo (mesmo id):

{
  "data": {
    "lead": {
      "id": "3f6c2a9e-0000-4000-8000-000000000010",
      "name": "Maria Souza",
      "email": "maria@exemplo.com.br",
      "phone": "+55 11 90000-0000",
      "tags": ["lead-api", "teste"],
      "url": "https://dattacrm.com.br/leads/3f6c2a9e-0000-4000-8000-000000000010"
    },
    "result": "matched"
  }
}

Os campos omitidos acima são os mesmos da resposta do Passo 2. Se quiser ver também o número do status (200 aqui, 201 no Passo 2), acrescente -i logo depois de curl (ou de curl.exe, no Windows).

O matched significa “encontrei um lead igual e não criei outro”. Para decidir se é o mesmo lead, a API procura primeiro pelo telefone e depois pelo e-mail. Por isso mandar o mesmo contato várias vezes não gera lead duplicado.

No matched, a API só preenche o que está vazio

Quando o lead já existe, o POST /leads não sobrescreve nada que já está preenchido. Ele:

• preenche os campos que estão vazios;
• junta as tags e as listas novas às que o lead já tem;
• nunca apaga tags nem troca um dado já preenchido.

A exceção é a atribuição (UTMs e rastreio, veja abaixo): o valor que chega preenchido passa a ser o do lead, porque conta o clique mais recente. O que chega vazio não apaga nada.

Se o lead da Maria já tem o nome “Maria Souza” e você mandar “Maria S.”, o nome continua “Maria Souza”. É de propósito: um formulário antigo não desfaz o que alguém já corrigiu no CRM.

Se você quer que um lead que já existe não seja tocado de jeito nenhum, mande também "mode": "createOnly". Nesse modo, a API devolve o lead como está e não altera nada.

Cada POST /leads aceito também registra uma Entrada por integração na jornada do lead, com as UTMs daquela chamada e a lista de destino. Dois campos opcionais deixam essa entrada mais precisa:

• occurredAt: quando o lead foi captado na origem, em ISO 8601 com fuso ("2026-10-30T09:15:00-03:00"). Sem ele, vale a hora da chamada. Um lead novo nasce com essa data e hora. Sem fuso ou mais de 5 minutos no futuro, a resposta é 400 validation_error.
• eventId: o identificador do envio na sua ferramenta (até 200 caracteres). Repetir a chamada com o mesmo eventId para o mesmo lead não registra outra entrada, então dá para reenviar sem duplicar.

O createOnly de um lead que já existe e o contato oculto não registram entrada.

UTMs e rastreio de clique

Além do bloco utm (source, medium, campaign, term, content e id, este último o utm_id), o POST /leads aceita o bloco tracking, com o rastreio do clique e da página:

Campo	O que é	Tamanho máximo
fbclid	Identificador de clique do Meta	500
gclid	Identificador de clique do Google Ads	500
ttclid	Identificador de clique do TikTok	500
ctwaClid	Identificador de clique de anúncio para o WhatsApp	500
sourceId	Identificador do anúncio de origem (anúncios para o WhatsApp)	500
pageUrl	Endereço da página onde o lead foi captado	2048
referrer	Endereço de onde a pessoa veio antes da página	2048

{
  "email": "maria@exemplo.com.br",
  "listId": "ID_DA_SUA_LISTA",
  "utm": { "source": "meta", "campaign": "black", "id": "120210000000" },
  "tracking": {
    "fbclid": "IwAR0abc",
    "pageUrl": "https://seusite.com.br/oferta?utm_source=meta",
    "referrer": "https://www.instagram.com/"
  }
}

Tudo é opcional, e campo vazio é ignorado. Os valores vão para o lead e para a entrada daquela chamada na jornada, como os das UTMs, e chegam aos relatórios de origem e aos dashboards. O pageUrl também vale como URL de conversão do lead.

Tudo é feito por inteiro ou nada: se algo da chamada falhar (por exemplo, uma etapa que não é da sua conta ou o limite do plano), nada é gravado.

Alterar um dado: PATCH /leads/{id}

Para trocar um dado que já está preenchido, use o PATCH /leads/{id}, com o id do lead no lugar de {id}. Ele só muda o que você mandar.

curl -X PATCH https://dattacrm.com.br/api/v1/leads/3f6c2a9e-0000-4000-8000-000000000010 \
  -H "Authorization: Bearer crm_live_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Souza Lima",
    "addTags": ["cliente"]
  }'

A resposta tem status 200 e o lead já atualizado, em data.lead.

Duas regras do PATCH:

• O corpo é estrito. Qualquer campo que a API não conhece faz a chamada falhar com validation_error. Você também precisa mandar pelo menos um campo.
• Para tags, use addTags e removeTags. O campo tags existe no POST /leads, mas não existe no PATCH. O mesmo vale para listas: addListIds e removeListIds.

A etapa, o valor e o motivo da perda não são mais do lead, e sim do negócio dele em cada lista, e ficam em lists[]. Para mudar a etapa, use PATCH /leads/{id}/lists/{listId} com stageId (e lossReasonId quando a etapa for Perdido). Mandar stageId, pipelineId, value, probability ou lossReason no POST /leads ou no PATCH /leads/{id} falha com 400 field_moved. Os motivos de perda saem de GET /loss-reasons, e as etapas de cada lista, de GET /lists (hasFunnel e stages).

Mudar a etapa, o responsável ou as tags dispara as mesmas automações e eventos de quando alguém faz isso na tela do CRM. Veja todos os campos na operação update_lead.

A mesma chamada pelo n8n

No n8n, o nó HTTP Request faz o mesmo POST /leads. Funciona hoje, sem instalar nada além do n8n.

1. Adicione o nó HTTP Request. No seu fluxo, clique em +, procure por HTTP Request e escolha o nó.

2. Configure o método e o endereço. Em Method, escolha POST. Em URL, cole:

   https://dattacrm.com.br/api/v1/leads

3. Configure a autenticação. Em Authentication, escolha Generic Credential Type. Em Generic Auth Type, escolha Header Auth.

4. Crie a credencial com a chave. Em Header Auth, clique em Create new credential e preencha:

   • Name: Authorization
   • Value: Bearer crm_live_SUA_CHAVE_AQUI

   Troque pelo valor da sua chave e mantenha a palavra Bearer e o espaço antes dela. Salve a credencial.

5. Ligue o envio do corpo. Ligue Send Body. Em Body Content Type, escolha JSON. Em Specify Body, escolha Using JSON.

6. Cole o corpo JSON. No campo JSON, cole:

   {
     "name": "Maria Souza",
     "email": "maria@exemplo.com.br",
     "phone": "+55 11 90000-0000",
     "tags": ["lead-api", "teste"]
   }

7. Execute o nó. Clique em Execute step. A saída mostra a mesma resposta dos exemplos acima, com result igual a created (ou matched, se o lead já existir).

Dados vindos de outro nó

No fluxo de verdade, o nome, o e-mail e o telefone vêm do nó anterior (um formulário, uma planilha, um anúncio). Em vez de valores fixos, monte o corpo com as fórmulas do n8n, como em Mandar leads para o CRM.

Se o nó falhar, a saída de erro mostra o code e o requestId. Veja o que fazer em Erros comuns.

Onde ver todos os campos

O POST /leads aceita mais coisas que as deste exemplo: listas, responsável, campos personalizados, origem, UTMs e rastreio de clique. Estão todas na Referência técnica da API, na operação upsert_lead (e na get_me, do primeiro teste).

Próximo passo

Próximo passo Erros comuns Entenda cada código de erro da API e como resolver.