Atualizar um lead

PATCH

/leads/{id}

const url = 'https://dattacrm.com.br/api/v1/leads/0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"name":"example","email":"example","phone":"example","stageId":"0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f","ownerId":"0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f","value":1,"probability":1,"lossReason":"example","customFields":{"additionalProperty":"example"},"addTags":["example"],"removeTags":["example"],"addListIds":["0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f"],"removeListIds":["0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f"]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request PATCH \
  --url https://dattacrm.com.br/api/v1/leads/0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "email": "example", "phone": "example", "stageId": "0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f", "ownerId": "0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f", "value": 1, "probability": 1, "lossReason": "example", "customFields": { "additionalProperty": "example" }, "addTags": [ "example" ], "removeTags": [ "example" ], "addListIds": [ "0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f" ], "removeListIds": [ "0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f" ] }'

Altera campos de um lead existente: nome, e-mail, telefone, responsável e campos personalizados, e acrescenta ou remove tags e listas. Só muda o que vier no corpo (exige pelo menos um campo). Mudar o responsável e mexer em tags disparam os mesmos eventos e automações da edição pela tela. Tudo é gravado junto: se algo falhar, nada é gravado. Etapa, valor e motivo da perda são do negócio (lead × lista): para eles use PATCH /leads/{id}/lists/{listId}; enviá-los aqui responde 400 field_moved. Responde 404 para lead ou responsável que não existem na conta e 409 quando o telefone ou o e-mail já é de outro lead (inclusive de um contato oculto, que conta na unicidade).

Authorizations

bearerAuth

Parameters

Path Parameters

required

Identificador do lead.

string format: uuid

/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

Example

0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f

Identificador do lead.

Request Body^required

application/json

Campos a alterar. O que não vem no corpo não muda; null limpa os campos que aceitam vazio. Exige pelo menos um campo.

object

name

Novo nome do lead (1 a 120 caracteres).

string

>= 1 characters <= 120 characters

email

Any of:

string
null

string

>= 1 characters <= 254 characters

phone

Any of:

string
null

string

<= 64 characters

stageId

Any of:

string
null

Identificador único (UUID).

string format: uuid

/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

Example

0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f

ownerId

Any of:

string
null

Identificador único (UUID).

string format: uuid

/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

Example

0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f

value

Removido: o valor é do negócio (lead × lista). Enviar este campo responde 400 field_moved; use PATCH /leads/{id}/lists/{listId} (update_lead_in_list).

number

<= 9999999999.99

probability

Removido: não há mais probabilidade por etapa. Enviar este campo responde 400 field_moved; use PATCH /leads/{id}/lists/{listId} (update_lead_in_list).

number

<= 100

lossReason

Any of:

string
null

string

<= 500 characters

customFields

Campos personalizados, indexados pela chave do campo (veja list_custom_fields). Mescla com os que o lead já tem: só as chaves enviadas mudam. Valor null remove a chave. O campo origem do lead, depois de definido, não é trocado.

object

key

additional properties

Valor do campo.

addTags

Tags a acrescentar, pelo nome (até 30). Tag nova é criada no catálogo da conta. Tag automática é ignorada: o CRM a põe e tira pela regra dela.

Array<string>

<= 30 items

removeTags

Tags a remover do lead, pelo nome (até 30), sem diferenciar maiúsculas. Tag que o lead não tem e tag automática são ignoradas.

Array<string>

<= 30 items

addListIds

Listas a que acrescentar o lead (até 100). Lista de outra conta é ignorada.

Array<string>

<= 100 items

removeListIds

Listas das quais tirar o lead (até 100). Lista em que o lead não está é ignorada.

Array<string>

<= 100 items

Responses

200

Sucesso.

application/json

object

data

required

O lead depois da atualização.

object

lead

required

Lead (contato/card do funil) no formato público da API.

object

required

Identificador do lead.

string format: uuid

/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

name

required

Nome do lead.

string

email

required

E-mail do lead, ou null quando não há.

string | null

phone

required

Telefone no formato informado, ou null quando não há.

string | null

tags

required

Tags do lead, pelo nome.

Array<string>

listIds

required

Listas das quais o lead faz parte. Pode ficar vazio.

Array<string>

ownerId

required

Any of:

string
null

Identificador único (UUID).

string format: uuid

/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

customFields

required

Campos personalizados do lead, indexados pela chave do campo.

object

key

additional properties

Valor do campo.

origin

required

Primeira origem do lead (site, whatsapp ou instagram). Gravada na criação; nunca muda.

string

Allowed values: site whatsapp instagram

source

required

Rótulo da origem do lead: “Site”, “WhatsApp” ou “Instagram”.

string

lists

required

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}.

Array<object>

Negócio do lead numa lista: a lista, a pasta, a etapa, o valor e o motivo da perda.

object

listId

required

Identificador da lista.

string format: uuid

/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

listName

required

Nome da lista.

string

folderId

required

Identificador da pasta da lista.

string format: uuid

/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

folderName

required

Nome da pasta da lista.

string

origin

required

Origem da lista (site, whatsapp ou instagram).

string

Allowed values: site whatsapp instagram

stageId

required

Any of:

string
null

Identificador único (UUID).

string format: uuid

/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

stageName

required

Nome da etapa, ou null em lista de Site.

string | null

stageKind

required

Any of:

string
null

string

Allowed values: active won lost

stageEnteredAt

required

Any of:

string
null

Data e hora em ISO 8601, com fuso.

string format: date-time

/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$/

value

required

Valor do negócio nesta lista, em reais. Zero quando não definido.

number

lossReasonId

required

Any of:

string
null

Identificador único (UUID).

string format: uuid

/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

utm

required

Parâmetros UTM de atribuição do lead.

object

source

required

Utm_source do último toque.

string | null

medium

required

Utm_medium do último toque.

string | null

campaign

required

Utm_campaign do último toque.

string | null

term

required

Utm_term do último toque.

string | null

content

required

Utm_content do último toque.

string | null

hidden

required

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.

boolean

hiddenAt

required

Any of:

string
null

Data e hora em ISO 8601, com fuso.

string format: date-time

createdAt

required

Quando o lead foi criado.

string format: date-time

updatedAt

required

Quando o lead foi alterado pela última vez.

string format: date-time

url

required

Link da ficha do lead no CRM, ou null quando o endereço não é conhecido.

string | null

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"
    }
  }
}

Headers

X-Request-Id

string

Identificador da requisição, para suporte.

X-RateLimit-Limit

integer

Máximo de requisições por janela de 60 segundos para esta chave.

X-RateLimit-Remaining

integer

Requisições restantes na janela atual.

X-RateLimit-Reset

integer

Fim da janela atual, em milissegundos desde a época Unix (epoch ms).

400

Dados inválidos (validation_error) ou stageId, value, probability ou lossReason, que agora são do negócio (field_moved: use PATCH /leads/{id}/lists/{listId}).

application/json

Formato de erro da API.

object

error

required

object

code

required

Código estável do erro, ex.: validation_error.

string

message

required

Mensagem legível em português.

string

details

Detalhes extras, ex.: lista de campos inválidos.

requestId

required

Identificador da requisição, para suporte.

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

X-Request-Id

string

Identificador da requisição, para suporte.

401

Chave ausente, inválida (invalid_api_key), vencida (api_key_expired) ou revogada (api_key_revoked).

application/json

Formato de erro da API.

object

error

required

object

code

required

Código estável do erro, ex.: validation_error.

string

message

required

Mensagem legível em português.

string

details

Detalhes extras, ex.: lista de campos inválidos.

requestId

required

Identificador da requisição, para suporte.

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

X-Request-Id

string

Identificador da requisição, para suporte.

403

A chave é somente leitura e a operação grava dados (insufficient_scope).

application/json

Formato de erro da API.

object

error

required

object

code

required

Código estável do erro, ex.: validation_error.

string

message

required

Mensagem legível em português.

string

details

Detalhes extras, ex.: lista de campos inválidos.

requestId

required

Identificador da requisição, para suporte.

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

X-Request-Id

string

Identificador da requisição, para suporte.

404

Recurso não encontrado (not_found).

application/json

Formato de erro da API.

object

error

required

object

code

required

Código estável do erro, ex.: validation_error.

string

message

required

Mensagem legível em português.

string

details

Detalhes extras, ex.: lista de campos inválidos.

requestId

required

Identificador da requisição, para suporte.

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

X-Request-Id

string

Identificador da requisição, para suporte.

409

Conflito com o estado atual (conflict), contato oculto, cujo negócio não muda (lead_hidden), ou limite do plano atingido (plan_limit).

application/json

Formato de erro da API.

object

error

required

object

code

required

Código estável do erro, ex.: validation_error.

string

message

required

Mensagem legível em português.

string

details

Detalhes extras, ex.: lista de campos inválidos.

requestId

required

Identificador da requisição, para suporte.

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

X-Request-Id

string

Identificador da requisição, para suporte.

413

O corpo da requisição passa de 256 KB (payload_too_large).

application/json

Formato de erro da API.

object

error

required

object

code

required

Código estável do erro, ex.: validation_error.

string

message

required

Mensagem legível em português.

string

details

Detalhes extras, ex.: lista de campos inválidos.

requestId

required

Identificador da requisição, para suporte.

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

X-Request-Id

string

Identificador da requisição, para suporte.

429

Limite de requisições atingido (rate_limited). Aguarde Retry-After segundos.

application/json

Formato de erro da API.

object

error

required

object

code

required

Código estável do erro, ex.: validation_error.

string

message

required

Mensagem legível em português.

string

details

Detalhes extras, ex.: lista de campos inválidos.

requestId

required

Identificador da requisição, para suporte.

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

X-Request-Id

string

Identificador da requisição, para suporte.

X-RateLimit-Limit

integer

Máximo de requisições por janela de 60 segundos para esta chave.

X-RateLimit-Remaining

integer

Requisições restantes na janela atual.

X-RateLimit-Reset

integer

Fim da janela atual, em milissegundos desde a época Unix (epoch ms).

Retry-After

integer

Segundos até poder tentar de novo.

500

Erro interno (internal_error). Informe o requestId ao suporte.

application/json

Formato de erro da API.

object

error

required

object

code

required

Código estável do erro, ex.: validation_error.

string

message

required

Mensagem legível em português.

string

details

Detalhes extras, ex.: lista de campos inválidos.

requestId

required

Identificador da requisição, para suporte.

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

X-Request-Id

string

Identificador da requisição, para suporte.

503

O CRM está em modo somente leitura durante uma migração (maintenance). Tente de novo depois de Retry-After segundos.

application/json

Formato de erro da API.

object

error

required

object

code

required

Código estável do erro, ex.: validation_error.

string

message

required

Mensagem legível em português.

string

details

Detalhes extras, ex.: lista de campos inválidos.

requestId

required

Identificador da requisição, para suporte.

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

X-Request-Id

string

Identificador da requisição, para suporte.

Retry-After

integer

Segundos até poder tentar de novo.

Atualizar um lead

Authorizations

Parameters

Path Parameters

Example

Request Body required

Example

Example

Responses

200

Example

Headers

400

Example generated

Headers

401

Example generated

Headers

403

Example generated

Headers

404

Example generated

Headers

409

Example generated

Headers

413

Example generated

Headers

429

Example generated

Headers

500

Example generated

Headers

503

Example generated

Headers

Request Body^required

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated