Mover ou editar o negócio de um lead numa lista

PATCH

/leads/{id}/lists/{listId}

const url = 'https://dattacrm.com.br/api/v1/leads/0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f/lists/0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"stageId":"0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f","value":1,"lossReasonId":"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/lists/0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "stageId": "0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f", "value": 1, "lossReasonId": "0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f" }'

Altera o negócio (lead × lista): etapa, valor e motivo da perda. Só a lista com funil tem etapa (WhatsApp e Instagram; veja hasFunnel em list_lists). Mudar de etapa passa pelo mesmo caminho do quadro: atividade, automações, rastreamento e webhooks (deal.stage_changed, deal.won, deal.lost). Mover para Perdido exige lossReasonId. Tudo é gravado junto: se algo falhar, nada é gravado. Contato oculto responde 409 lead_hidden e nada muda. Devolve o negócio depois da edição.

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.

listId

required

Identificador da lista em que o lead tem o negócio.

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 da lista em que o lead tem o negócio.

Request Body^required

application/json

Campos do negócio a alterar. O que não vem no corpo não muda. Exige pelo menos um campo.

object

stageId

Etapa de destino, da própria lista (veja list_lists, campo stages). Mudar de etapa dispara os mesmos eventos e automações do quadro. Etapa de outra lista responde 400 stage_not_in_list; Perdido exige lossReasonId.

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

Valor do negócio nesta lista, em reais (zero a 9999999999.99). Sobrescreve o valor atual.

number

<= 9999999999.99

lossReasonId

Motivo da perda (veja list_loss_reasons). Obrigatório ao mover para uma etapa Perdido; num negócio já perdido, troca o motivo. Motivo de outra conta responde 404.

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

Responses

200

Sucesso.

application/json

object

data

required

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)$/

Example

{
  "data": {
    "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"
  }
}

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), lista sem funil (list_has_no_funnel), etapa de outra lista (stage_not_in_list) ou Perdido sem motivo (loss_reason_required).

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

Lead que não existe, que não está na lista (not_found) ou motivo da perda que não existe nesta conta. Nada é gravado.

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.

Mover ou editar o negócio de um lead numa lista

Authorizations

Parameters

Path Parameters

Example

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