Criar ou atualizar um lead
const url = 'https://dattacrm.com.br/api/v1/leads';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"name":"example","email":"example","phone":"example","tags":["example"],"listId":"0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f","listIds":["0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f"],"pipelineId":"0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f","stageId":"0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f","ownerId":"0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f","value":1,"customFields":{"additionalProperty":"example"},"source":"example","utm":{"source":"example","medium":"example","campaign":"example","term":"example","content":"example","id":"example"},"tracking":{"fbclid":"example","gclid":"example","ttclid":"example","ctwaClid":"example","sourceId":"example","pageUrl":"example","referrer":"example"},"occurredAt":"2026-04-15T12:00:00Z","eventId":"example","mode":"upsert"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://dattacrm.com.br/api/v1/leads \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "name": "example", "email": "example", "phone": "example", "tags": [ "example" ], "listId": "0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f", "listIds": [ "0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f" ], "pipelineId": "0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f", "stageId": "0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f", "ownerId": "0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f", "value": 1, "customFields": { "additionalProperty": "example" }, "source": "example", "utm": { "source": "example", "medium": "example", "campaign": "example", "term": "example", "content": "example", "id": "example" }, "tracking": { "fbclid": "example", "gclid": "example", "ttclid": "example", "ctwaClid": "example", "sourceId": "example", "pageUrl": "example", "referrer": "example" }, "occurredAt": "2026-04-15T12:00:00Z", "eventId": "example", "mode": "upsert" }'Principal porta de entrada de leads. Casa pelo telefone, depois pelo e-mail: se o lead já existe, mescla sem sobrescrever o que está preenchido e junta tags e listas; se não existe, cria. Aceita responsável, campos personalizados e UTMs. Cada envio aceito grava uma captura na jornada do lead, com a hora occurredAt (ou a da chegada), as UTMs do envio e a lista de destino; eventId evita a captura repetida no reenvio. Contato oculto e createOnly de lead existente não gravam captura. Etapa e valor não vão aqui: são do negócio (lead × lista), e stageId, pipelineId ou value respondem 400 field_moved (use PATCH /leads/{id}/lists/{listId}). Tudo é gravado junto: se algo falhar (responsável de outra conta, limite do plano), nada é gravado. Responde 201 com result: created ou 200 com result: matched.
Authorizations
Seção intitulada “Authorizations ”Request Body required
Seção intitulada “Request Body required ”Dados do lead a criar ou atualizar.
object
Nome do lead (1 a 120 caracteres). Sem nome, vale o e-mail ou o telefone.
E-mail do lead (espaços nas pontas e maiúsculas são ignorados; até 254 caracteres). Identifica o lead sem diferenciar maiúsculas. Formato inválido não recusa o lead: o e-mail é gravado como chegou e aparece com alerta. Informe e-mail ou telefone.
Telefone do lead, em qualquer formato (máscara, +DDI; até 64 caracteres); sem DDI vale o país padrão da conta. Identifica o lead quando tem de 8 a 15 dígitos. Formato fora disso não recusa o lead: com dois números no campo vale o primeiro, e o resto é gravado com os dígitos que vieram, aparece com alerta e não identifica nem junta o lead com ninguém. Informe e-mail ou telefone.
Tags a acrescentar, pelo nome (até 30). Nunca remove tags que o lead já tem. Tag automática é ignorada: o CRM a põe e tira pela regra dela.
Lista de destino do lead. Lead novo nasce com a origem desta lista. Sem ela, vale a primeira de listIds. A chave de API não tem lista: para criar um lead, informe listId ou listIds; sem nenhuma, a resposta é 400 list_required. Lead que já existe aceita o corpo sem lista. Lista de outra conta é ignorada.
Example
0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6fListas a acrescentar ao lead (até 100), além da de destino. Sem listId, a primeira é a de destino. Nunca tira o lead de uma lista.
Removido: não há mais funil da conta; cada lista com funil tem as suas etapas. Enviar este campo responde 400 field_moved; use PATCH /leads/{id}/lists/{listId} (update_lead_in_list).
Example
0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6fRemovido: a etapa é do negócio (lead × lista). Enviar este campo responde 400 field_moved; use PATCH /leads/{id}/lists/{listId} (update_lead_in_list).
Example
0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6fMembro responsável pelo lead (veja list_members). Lead novo recebe o responsável; lead existente só recebe quando não tem responsável, nunca é reatribuído. Membro de outra conta responde 404.
Example
0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6fRemovido: o valor é do negócio (lead × lista). Enviar este campo responde 400 field_moved; use PATCH /leads/{id}/lists/{listId} (update_lead_in_list).
Campos personalizados, indexados pela chave do campo (veja list_custom_fields).
object
Valor do campo.
Obsoleto: aceito e ignorado. A origem do lead é a da lista de destino (listId) e nunca muda depois da criação.
Parâmetros UTM de atribuição. Num lead existente só entram os que vierem preenchidos.
object
Utm_source.
Utm_medium.
Utm_campaign.
Utm_term.
Utm_content.
Utm_id.
Rastreio de clique e de página, além das UTMs. Vai para o lead e para a captura desta entrega. Num lead existente só entram os que vierem preenchidos.
object
Identificador de clique do Meta (fbclid), até 500 caracteres.
Identificador de clique do Google Ads (gclid), até 500 caracteres.
Identificador de clique do TikTok (ttclid), até 500 caracteres.
Identificador de clique de anúncio para o WhatsApp (ctwa_clid), até 500 caracteres.
Identificador do anúncio de origem (source_id, dos anúncios para o WhatsApp), até 500 caracteres.
Endereço da página onde o lead foi captado (page_url), até 2048 caracteres. Também vale como URL de conversão do lead.
Endereço de onde a pessoa veio antes da página de captação (referrer), até 2048 caracteres.
Quando o lead foi captado na origem, em ISO 8601 com fuso (ex.: 2026-10-30T09:15:00-03:00). Vai na captura desta entrega (o toque lead_capture da jornada) e, num lead novo, na data e na hora do lead. Sem ele, vale a hora da chegada. Sem fuso ou mais de 5 minutos no futuro responde 400 validation_error.
Identificador desta entrega na sua ferramenta (até 200 caracteres), para reenviar sem duplicar: a mesma entrega repetida para o mesmo lead não grava outra captura, a qualquer tempo. Sem ele, cada envio aceito grava uma captura.
upsert (padrão) cria o lead ou mescla no existente, sem sobrescrever o que já está preenchido. createOnly cria; se o lead já existir, devolve-o como está (matched), sem mesclar nada, nem etapa nem responsável.
Responses
Seção intitulada “ Responses ”O lead já existia e foi mesclado, ou devolvido como está no createOnly (result: matched).
object
O lead gravado e o que aconteceu com ele.
object
Lead (contato/card do funil) no formato público da API.
object
Identificador do lead.
Nome do lead.
E-mail do lead, ou null quando não há.
Telefone no formato informado, ou null quando não há.
Tags do lead, pelo nome.
Listas das quais o lead faz parte. Pode ficar vazio.
Campos personalizados do lead, indexados pela chave do campo.
object
Valor do campo.
Primeira origem do lead (site, whatsapp ou instagram). Gravada na criação; nunca muda.
Rótulo da origem do lead: “Site”, “WhatsApp” ou “Instagram”.
Negócios do lead: um por lista de que ele faz parte (lead × lista), em ordem alfabética. Etapa, valor e motivo da perda são do negócio; mude com PATCH /leads/{id}/lists/{listId}.
Negócio do lead numa lista: a lista, a pasta, a etapa, o valor e o motivo da perda.
object
Identificador da lista.
Nome da lista.
Identificador da pasta da lista.
Nome da pasta da lista.
Origem da lista (site, whatsapp ou instagram).
Nome da etapa, ou null em lista de Site.
Valor do negócio nesta lista, em reais. Zero quando não definido.
Parâmetros UTM de atribuição do lead.
object
Utm_source do último toque.
Utm_medium do último toque.
Utm_campaign do último toque.
Utm_term do último toque.
Utm_content do último toque.
Contato oculto (equipe, pessoal): não aparece nas telas nem em GET /leads (só com includeHidden=true), não entra em lista nem dispara automações ou webhooks. Ocultar e mostrar só pela tela.
Quando o lead foi criado.
Quando o lead foi alterado pela última vez.
Link da ficha do lead no CRM, ou null quando o endereço não é conhecido.
created quando o lead é novo (HTTP 201); matched quando já existia (HTTP 200).
Example
{ "data": { "lead": { "id": "0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f", "listIds": [ "0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f" ], "ownerId": "0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f", "origin": "site", "lists": [ { "listId": "0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f", "folderId": "0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f", "origin": "site", "stageId": "0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f", "stageKind": "active", "stageEnteredAt": "2026-10-19T12:00:00.000Z", "lossReasonId": "0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f" } ], "hiddenAt": "2026-10-19T12:00:00.000Z", "createdAt": "2026-10-19T12:00:00.000Z", "updatedAt": "2026-10-19T12:00:00.000Z" }, "result": "created" }}Headers
Seção intitulada “Headers ”Identificador da requisição, para suporte.
Máximo de requisições por janela de 60 segundos para esta chave.
Requisições restantes na janela atual.
Fim da janela atual, em milissegundos desde a época Unix (epoch ms).
Lead criado (result: created).
object
O lead gravado e o que aconteceu com ele.
object
Lead (contato/card do funil) no formato público da API.
object
Identificador do lead.
Nome do lead.
E-mail do lead, ou null quando não há.
Telefone no formato informado, ou null quando não há.
Tags do lead, pelo nome.
Listas das quais o lead faz parte. Pode ficar vazio.
Campos personalizados do lead, indexados pela chave do campo.
object
Valor do campo.
Primeira origem do lead (site, whatsapp ou instagram). Gravada na criação; nunca muda.
Rótulo da origem do lead: “Site”, “WhatsApp” ou “Instagram”.
Negócios do lead: um por lista de que ele faz parte (lead × lista), em ordem alfabética. Etapa, valor e motivo da perda são do negócio; mude com PATCH /leads/{id}/lists/{listId}.
Negócio do lead numa lista: a lista, a pasta, a etapa, o valor e o motivo da perda.
object
Identificador da lista.
Nome da lista.
Identificador da pasta da lista.
Nome da pasta da lista.
Origem da lista (site, whatsapp ou instagram).
Nome da etapa, ou null em lista de Site.
Valor do negócio nesta lista, em reais. Zero quando não definido.
Parâmetros UTM de atribuição do lead.
object
Utm_source do último toque.
Utm_medium do último toque.
Utm_campaign do último toque.
Utm_term do último toque.
Utm_content do último toque.
Contato oculto (equipe, pessoal): não aparece nas telas nem em GET /leads (só com includeHidden=true), não entra em lista nem dispara automações ou webhooks. Ocultar e mostrar só pela tela.
Quando o lead foi criado.
Quando o lead foi alterado pela última vez.
Link da ficha do lead no CRM, ou null quando o endereço não é conhecido.
created quando o lead é novo (HTTP 201); matched quando já existia (HTTP 200).
Example
{ "data": { "lead": { "id": "0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f", "listIds": [ "0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f" ], "ownerId": "0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f", "origin": "site", "lists": [ { "listId": "0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f", "folderId": "0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f", "origin": "site", "stageId": "0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f", "stageKind": "active", "stageEnteredAt": "2026-10-19T12:00:00.000Z", "lossReasonId": "0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f" } ], "hiddenAt": "2026-10-19T12:00:00.000Z", "createdAt": "2026-10-19T12:00:00.000Z", "updatedAt": "2026-10-19T12:00:00.000Z" }, "result": "created" }}Headers
Seção intitulada “Headers ”Identificador da requisição, para suporte.
Máximo de requisições por janela de 60 segundos para esta chave.
Requisições restantes na janela atual.
Fim da janela atual, em milissegundos desde a época Unix (epoch ms).
Dados inválidos (validation_error), lead novo sem lista (list_required), stageId, pipelineId ou value, que agora são do negócio (field_moved) ou chave enviada na URL (api_key_in_url).
Formato de erro da API.
object
object
Código estável do erro, ex.: validation_error.
Mensagem legível em português.
Detalhes extras, ex.: lista de campos inválidos.
Identificador da requisição, para suporte.
Example generated
{ "error": { "code": "example", "message": "example", "details": "example", "requestId": "example" }}Headers
Seção intitulada “Headers ”Identificador da requisição, para suporte.
Chave ausente, inválida (invalid_api_key), vencida (api_key_expired) ou revogada (api_key_revoked).
Formato de erro da API.
object
object
Código estável do erro, ex.: validation_error.
Mensagem legível em português.
Detalhes extras, ex.: lista de campos inválidos.
Identificador da requisição, para suporte.
Example generated
{ "error": { "code": "example", "message": "example", "details": "example", "requestId": "example" }}Headers
Seção intitulada “Headers ”Identificador da requisição, para suporte.
A chave é somente leitura e a operação grava dados (insufficient_scope).
Formato de erro da API.
object
object
Código estável do erro, ex.: validation_error.
Mensagem legível em português.
Detalhes extras, ex.: lista de campos inválidos.
Identificador da requisição, para suporte.
Example generated
{ "error": { "code": "example", "message": "example", "details": "example", "requestId": "example" }}Headers
Seção intitulada “Headers ”Identificador da requisição, para suporte.
Responsável (ownerId) não encontrado nesta conta (not_found). Nada é gravado.
Formato de erro da API.
object
object
Código estável do erro, ex.: validation_error.
Mensagem legível em português.
Detalhes extras, ex.: lista de campos inválidos.
Identificador da requisição, para suporte.
Example generated
{ "error": { "code": "example", "message": "example", "details": "example", "requestId": "example" }}Headers
Seção intitulada “Headers ”Identificador da requisição, para suporte.
Conflito com o estado atual (conflict), contato oculto, cujo negócio não muda (lead_hidden), ou limite do plano atingido (plan_limit).
Formato de erro da API.
object
object
Código estável do erro, ex.: validation_error.
Mensagem legível em português.
Detalhes extras, ex.: lista de campos inválidos.
Identificador da requisição, para suporte.
Example generated
{ "error": { "code": "example", "message": "example", "details": "example", "requestId": "example" }}Headers
Seção intitulada “Headers ”Identificador da requisição, para suporte.
O corpo da requisição passa de 256 KB (payload_too_large).
Formato de erro da API.
object
object
Código estável do erro, ex.: validation_error.
Mensagem legível em português.
Detalhes extras, ex.: lista de campos inválidos.
Identificador da requisição, para suporte.
Example generated
{ "error": { "code": "example", "message": "example", "details": "example", "requestId": "example" }}Headers
Seção intitulada “Headers ”Identificador da requisição, para suporte.
Limite de requisições atingido (rate_limited). Aguarde Retry-After segundos.
Formato de erro da API.
object
object
Código estável do erro, ex.: validation_error.
Mensagem legível em português.
Detalhes extras, ex.: lista de campos inválidos.
Identificador da requisição, para suporte.
Example generated
{ "error": { "code": "example", "message": "example", "details": "example", "requestId": "example" }}Headers
Seção intitulada “Headers ”Identificador da requisição, para suporte.
Máximo de requisições por janela de 60 segundos para esta chave.
Requisições restantes na janela atual.
Fim da janela atual, em milissegundos desde a época Unix (epoch ms).
Segundos até poder tentar de novo.
Erro interno (internal_error). Informe o requestId ao suporte.
Formato de erro da API.
object
object
Código estável do erro, ex.: validation_error.
Mensagem legível em português.
Detalhes extras, ex.: lista de campos inválidos.
Identificador da requisição, para suporte.
Example generated
{ "error": { "code": "example", "message": "example", "details": "example", "requestId": "example" }}Headers
Seção intitulada “Headers ”Identificador da requisição, para suporte.
O CRM está em modo somente leitura durante uma migração (maintenance). Tente de novo depois de Retry-After segundos.
Formato de erro da API.
object
object
Código estável do erro, ex.: validation_error.
Mensagem legível em português.
Detalhes extras, ex.: lista de campos inválidos.
Identificador da requisição, para suporte.
Example generated
{ "error": { "code": "example", "message": "example", "details": "example", "requestId": "example" }}Headers
Seção intitulada “Headers ”Identificador da requisição, para suporte.
Segundos até poder tentar de novo.