Listar e buscar leads

GET

/leads

const url = 'https://dattacrm.com.br/api/v1/leads?limit=50&listId=0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f&stageId=0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f&origin=site&originKind=site&updatedSince=2026-10-19T12%3A00%3A00.000Z&includeHidden=true';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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

curl --request GET \
  --url 'https://dattacrm.com.br/api/v1/leads?limit=50&listId=0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f&stageId=0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f&origin=site&originKind=site&updatedSince=2026-10-19T12%3A00%3A00.000Z&includeHidden=true' \
  --header 'Authorization: Bearer <token>'

Lista os leads da conta, do mais novo para o mais antigo, em páginas. Contatos ocultos ficam de fora, a não ser com includeHidden=true. Os filtros se combinam (todos precisam valer). Use nextCursor no parâmetro cursor para buscar a página seguinte; quando vier nulo, acabou.

Authorizations

bearerAuth

Parameters

Query Parameters

cursor

Cursor da página anterior (nextCursor).

string

Cursor da página anterior (nextCursor).

limit

Itens por página (1 a 200, padrão 50).

integer

default: 50 >= 1 <= 200

Itens por página (1 a 200, padrão 50).

email

Filtra pelo e-mail exato, sem diferenciar maiúsculas.

string

Filtra pelo e-mail exato, sem diferenciar maiúsculas.

phone

Filtra pelo telefone. Aceita qualquer formato (máscara, +DDI); sem DDI vale o país padrão da conta.

string

Filtra pelo telefone. Aceita qualquer formato (máscara, +DDI); sem DDI vale o país padrão da conta.

tag

Filtra por leads que têm esta tag (pelo nome).

string

Filtra por leads que têm esta tag (pelo nome).

listId

Filtra por leads que fazem parte desta 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)$/

Example

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

Filtra por leads que fazem parte desta lista.

stageId

Filtra por leads que têm algum negócio nesta etapa (a etapa é de uma lista; veja list_lists). Um lead em duas listas conta pela etapa de cada uma.

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

Filtra por leads que têm algum negócio nesta etapa (a etapa é de uma lista; veja list_lists). Um lead em duas listas conta pela etapa de cada uma.

origin

Filtra pela origem do lead (a primeira, gravada na criação): site, whatsapp ou instagram.

string

Allowed values: site whatsapp instagram

Filtra pela origem do lead (a primeira, gravada na criação): site, whatsapp ou instagram.

originKind

Obsoleto: use origin. Tipos antigos viram a origem nova (importacao, venda, integracao e manual viram site). Ignorado quando origin vem junto.

string

Allowed values: site whatsapp instagram importacao venda integracao manual

Obsoleto: use origin. Tipos antigos viram a origem nova (importacao, venda, integracao e manual viram site). Ignorado quando origin vem junto.

updatedSince

Só leads alterados a partir deste instante (inclusive), em ISO 8601.

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

Example

2026-10-19T12:00:00.000Z

Só leads alterados a partir deste instante (inclusive), em ISO 8601.

includeHidden

Com true, traz também os contatos ocultos (hidden: true). Padrão: só os visíveis.

string

Allowed values: true false

Com true, traz também os contatos ocultos (hidden: true). Padrão: só os visíveis.

Responses

200

Sucesso.

application/json

object

data

required

Leads da página, do mais novo para o mais antigo.

Array<object>

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

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

nextCursor

required

Cursor da próxima página; nulo na última página.

string | null

Example

{
  "data": [
    {
      "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 na requisição (validation_error), lead novo sem lista (list_required), campo que mudou de lugar (field_moved) ou chave enviada na URL (api_key_in_url).

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.

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.

Listar e buscar leads

Authorizations

Parameters

Query Parameters

Example

Example

Example

Responses

200

Example

Headers

400

Example generated

Headers

401

Example generated

Headers

429

Example generated

Headers

500

Example generated

Headers

Example ^generated

Example ^generated

Example ^generated

Example ^generated