Leads

Documentação do Mercado Livre

Confira todas as informações necessárias sobre as APIs Mercado Livre.

Última atualização em 07/05/2026

Leads

Um lead é um contato feito por um comprador que demonstrou interesse em uma publicação. Geralmente, trata-se de uma interação inicial. Essa interação pode ocorrer de diversas formas, incluindo:

whatsapp: um comprador utiliza o botão do WhatsApp.
question: um comprador faz uma pergunta.
call: um comprador utiliza o botão para realizar uma chamada.
schedule: o comprador agenda uma visita.
quotation: um comprador solicita uma cotação do imóvel (se disponível).

Consultar interessados nos itens do vendedor

O vendedor pode consultar todos os dados de contato dos interessados em seus itens, com a possibilidade de paginá-los por meio do parâmetro offset, que indica a posição do primeiro elemento a ser recuperado, e do parâmetro limit, que indica a quantidade máxima de elementos a obter. Além disso, os dados podem ser filtrados por um período de tempo específico, utilizando os parâmetros date_from e date_to. Para realizar uma busca mais específica, pode-se utilizar o parâmetro contact_types, que representa o tipo de contato a ser retornado.

Adicionalmente, o vendedor pode consultar os leads gerados por usuários não logados utilizando o parâmetro opcional include_guest=true, que adiciona à resposta padrão dois novos nós estruturais: guest e summary.

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
'https://api.mercadolibre.com/vis/users/$USER_ID/leads/buyers?offset=$OFFSET&limit=$LIMIT&date_from=$DATE_FROM&date_to=$DATE_TO&contact_types=$CONTACT_TYPES&item_id=$ITEM_ID&buyer_ids=$BUYER_IDS'

Parâmetros da consulta

Parâmetro	Tipo de Dado	Opcional	Valores / Descrição
USER_ID	int	Não	Identificador do vendedor.
OFFSET	int	Sim	Posição do primeiro elemento na lista. Valor padrão: 0.
LIMIT	int	Sim	Quantidade máxima de elementos da lista. Valor padrão: 10.
DATE_FROM	string (YYYY-MM-DD)	Sim	Data de início da busca. Valor padrão: 7 dias antes da data atual.
DATE_TO	string (YYYY-MM-DD)	Sim	Data de término da busca. Valor padrão: data atual.
CONTACT_TYPES	string	Sim	Tipos de contatos a retornar. Caso não seja enviado, todos os tipos serão retornados.
ITEM_ID	string	Sim	Identificador do item, formato MLX12345678.
BUYER_IDS	int ou lista de int	Sim	Identificadores do comprador, separados por vírgula caso sejam mais de um.
INCLUDE_GUEST	boolean	Sim	Indica se os leads gerados por usuários não logados (guest) devem ser incluídos na resposta. Ao ser ativado, as estruturas guest e summary são adicionadas.

Nota:

Os parâmetros de paginação (offset e limit) não afetam os leads do tipo guest, que são sempre retornados de forma completa de acordo com o intervalo de date_from e date_to solicitado.

Resposta de exemplo:

{
  "results": [
    {
      "id": 1914813422,
      "item_id": "MLA2919342112",
      "name": "Test Test",
      "email": "test.test+1914813422@mercadolibre.com",
      "phone": "+56 01 1111-1111",
      "identification_number": "7894564123-7",
      "identification_type": "RUT",
      "leads": [
        {
          "id": "214e7c51-076b-495c-aec4-a326e8eecb0d",
          "uuid": "214e7c51-076b-495c-aec4-a326e8eecb0d",
          "channel": "question",
          "contact_type": "question",
          "created_at": "2025-06-12T20:56:45.174Z",
          "external_id": "13358605478",
          "item_id": "MLA2919342112",
          "status": "active"
        }
      ]
    },
    {
      "id": 1554225116,
      "item_id": "MLA2832508942",
      "name": "Tester Inmo",
      "email": "Tester.inmo+1554225116@mercadolibre.com",
      "phone": "+56 572369293",
      "identification_number": "11111111-1",
      "identification_type": "RUT",
      "leads": [
        {
          "id": "237df990-115b-4d16-b80e-cc70f9fafb84",
          "uuid": "237df990-115b-4d16-b80e-cc70f9fafb84",
          "channel": "question",
          "contact_type": "question",
          "created_at": "2025-05-26T17:46:51.2Z",
          "external_id": "13345640067",
          "item_id": "MLA2832508942",
          "status": "active"
        }
      ]
    },
    {
      "id": 1914813422,
      "item_id": "MLA1612742785",
      "name": "Test Test",
      "email": "test.test+1914813422@mercadolibre.com",
      "phone": "+56 01 1111-1111",
      "identification_number": "78708960-7",
      "identification_type": "RUT",
      "leads": [
        {
          "id": "9fe96952-454c-47bf-abb5-657f069592e9",
          "uuid": "9fe96952-454c-47bf-abb5-657f069592e9",
          "channel": "question",
          "contact_type": "question",
          "created_at": "2025-05-20T15:05:13.603Z",
          "external_id": "13341528179",
          "item_id": "MLA1612742785",
          "status": "active"
        }
      ]
    }
  ],
  "paging": {
    "offset": 0,
    "limit": 10,
    "total": 3
  },
  "date_from": "2025-04-18",
  "date_to": "2025-06-18"
}

Descrição da resposta

Parâmetro	Tipo	Descrição
results	array<objeto>	Lista de resultados, cada um representando um comprador com seus detalhes e leads.
results.id	número	Identificador único do comprador.
results.item_id	string	Identificador do item associado ao comprador.
results.name	string	Nome do comprador. Dado visível apenas se o acesso for por usuário logado.
results.email	string	E-mail do comprador. Dado visível apenas se o acesso for por usuário logado.
results.phone	string	Número de telefone do comprador. Dado visível apenas se o acesso for por usuário logado.
results.identification_number	string	Número de identificação do comprador. Dado visível apenas se o acesso for por usuário logado.
results.identification_type	string	Tipo de identificação do comprador. Dado visível apenas se o acesso for por usuário logado.
results.leads	array<objeto>	Lista de leads gerados pelo comprador.
results.leads.id	string	Identificador único do lead.
results.leads.uuid	string	UUID do lead (igual ao seu ID).
results.leads.channel	string	Canal pelo qual o lead foi gerado (por exemplo, "question").
results.leads.contact_type	string	Tipo de contato do lead (por exemplo, "question").
results.leads.created_at	string (data/hora)	Data e hora de criação do lead no formato ISO 8601.
results.leads.external_id	string	Identificador externo do lead (por exemplo, ID da pergunta).
results.leads.item_id	string	Identificador do item associado ao lead, formato MLX########.
results.leads.status	string	Status do lead.
paging	objeto	Informações sobre a paginação dos resultados.
paging.offset	número	Posição do primeiro elemento na lista de resultados.
paging.limit	número	Quantidade máxima de elementos na lista de resultados.
paging.total	número	Quantidade total de elementos disponíveis.
date_from	string (YYYY-MM-DD)	Data de início do período de busca no formato YYYY-MM-DD.
date_to	string (YYYY-MM-DD)	Data de fim do período de busca no formato YYYY-MM-DD.

Exemplo de chamada com o parâmetro opcional include_guest=true

O objetivo é permitir que o vendedor quantifique o volume total de interesse e cliques em suas publicações provenientes de usuários não registrados, facilitando para uma análise de métricas mais completa e real.

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/vis/users/3052668868/leads/buyers?offset=0&limit=10&date_from=2026-01-15&date_to=2026-01-22&contact_types=credit,question,whatsapp&include_guest=true

Resposta:

{
    "results": [
        {
            "id": 2522572034,
            "item_id": "MLC3404674016",
            "name": "Test Test",
            "email": "test_user_2030409702@testuser.com",
            "phone": "+56 01 1111-1111",
            "identification_number": "67602099-3",
            "identification_type": "RUT",
            "leads": [
                {
                    "id": "b711e264-ec67-480e-90b2-444d8f47d5ed",
                    "uuid": "b711e264-ec67-480e-90b2-444d8f47d5ed",
                    "channel": "whatsapp",
                    "contact_type": "whatsapp",
                    "created_at": "2026-01-22T21:01:47Z",
                    "external_id": "",
                    "item_id": "MLC3404674016",
                    "status": "active"
                }
            ]
        },
        {
            "id": 2522572034,
            "item_id": "MLC3404028058",
            "name": "Test Test",
            "email": "test_user_2030409702@testuser.com",
            "phone": "+56 01 1111-1111",
            "identification_number": "67602099-3",
            "identification_type": "RUT",
            "leads": [
                {
                    "id": "5a6732a1-6051-4281-a470-d81cb43acecb",
                    "uuid": "5a6732a1-6051-4281-a470-d81cb43acecb",
                    "channel": "question",
                    "contact_type": "question",
                    "created_at": "2026-01-22T20:44:05.3Z",
                    "external_id": "13510887742",
                    "item_id": "MLC3404028058",
                    "status": "active"
                }
            ]
        }
    ],
    "paging": {
        "offset": 0,
        "limit": 10,
        "total": 2
    },
    "date_from": "2026-01-15",
    "date_to": "2026-01-22",
    "guest": [
        {
            "item_id": "MLC3404674016",
            "leads": [
                {
                    "id": "56c71b07-f347-41e2-8f63-4f81dda74491",
                    "contact_type": "whatsapp",
                    "status": "active",
                    "created_at": "2026-01-22T20:30:52Z"
                }
            ]
        }
    ],
    "summary": [
        {
            "item_id": "MLC3404674016",
            "total": 2,
            "user": 1,
            "guest": 1
        },
        {
            "item_id": "MLC3404028058",
            "total": 1,
            "user": 1,
            "guest": 0
        }
    ]
}

Campos adicionais ao utilizar o parâmetro include_guest=true

Parâmetro	Tipo	Descrição
guest	array<objeto>	Contém a lista de leads gerados por usuários não logados (guest), agrupados por item.
guest.item_id	string	Identificador do item.
guest.leads	array	Contém a lista de leads gerados por usuários não logados para o item.
guest.leads.id	string	Identificador único do lead.
guest.leads.contact_type	string	Tipo de contato do lead (por exemplo, "whatsapp").
guest.leads.status	string	Status do lead.
guest.leads.created_at	string (data/hora)	Data e hora de criação do lead no formato ISO 8601.
summary	array<objeto>	Contém um resumo por item da quantidade total de leads e sua distribuição por tipo de usuário.
summary.item_id	string	Identificador do item.
summary.total	string	Quantidade total de leads do item no período consultado.
summary.user	string	Quantidade de leads gerados por usuários logados.
summary.guest	string	Quantidade de leads gerados por usuários não logados.

Consultar Leads

A seguir, são apresentados exemplos de como realizar consultas de leads específicos. Lembre-se de ter em mãos seu Access Token gerado no módulo de Autorização.

Consultar todos os leads de um usuário

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
'https://api.mercadolibre.com/vis/users/$USER_ID/leads/buyers'

Parâmetros

Parâmetro	Tipo	Opcional	Valores
ACCESS_TOKEN	string	Não	Token válido para o usuário consultado.
USER_ID	string	Não	ID do vendedor a ser consultado.

Consultar todos os leads de um item associado a um vendedor

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
'https://api.mercadolibre.com/vis/users/$USER_ID/leads/buyers?item_id=MLX1234'

Parâmetros

Parâmetro	Tipo	Opcional	Valores
ACCESS_TOKEN	string	Não	Token válido para o usuário consultado.
USER_ID	string	Não	ID do vendedor a ser consultado.
item_id	string	Não	ID do item específico a ser consultado.

Consultar os leads de um tipo de contato específico

É possível iterar o atributo contact_type com os seguintes valores: whatsapp, question, call, quotation e schedule. Este último retornará resultados apenas se o item tiver essa funcionalidade disponível. Caso contrário, não retornará erro, mas sim um array vazio.

A seguir, é apresentado um exemplo utilizando o contact_type igual a whatsapp:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
'https://api.mercadolibre.com/vis/users/$USER_ID/leads/buyers?contact_types=whatsapp'

Parâmetros

Parâmetro	Tipo	Opcional	Valores
ACCESS_TOKEN	string	Não	Token válido para o usuário consultado.
USER_ID	string	Não	ID do vendedor a ser consultado.
contact_types	string	Não	Tipo de lead que deseja consultar: whatsapp, question, call, schedule ou quotation.

O código de resposta esperado é 200, retornando um JSON com as informações solicitadas. Caso o código de resposta seja diferente, verifique a seção de possíveis erros.

Você receberá uma resposta semelhante a esta:

{
  "results": [
    {
      "id": 2678328,
      "item_id": "MLA1430828018",
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "+5491198765432",
      "leads": [
        {
          "id": "6b4aebf8-5570-47b8-9224-c1c177621575",
          "contact_type": "question",
          "created_at": "2024-05-14T14:15:39Z",
          "external_id": "12776297658",
          "item_id": "MLA1430828018",
          "buyer_id": 2678328,
          "status": "active",
          "sub_status": "answered"
        }
      ]
    }
  ],
  "paging": {
    "offset": 0,
    "limit": 10,
    "total": 1
  },
  "date_from": "2024-05-14",
  "date_to": "2024-05-24"
}

Essa resposta é semelhante à apresentada anteriormente e pode ser consultada em detalhes na tabela correspondente.

Obter detalhes de um Lead

Quando o Mercado Livre notifica sobre a criação de um novo lead relacionado aos interessados, ele menciona o ID na mensagem. Para obter os detalhes, você deve usar esse identificador no recurso /vis/leads/$LEAD_ID, o que fornecerá as informações correspondentes.

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/vis/leads/$LEAD_ID

Parâmetros

Parâmetro	Tipo	Opcional	Valores
ACCESS_TOKEN	string	Não	Lembre-se de utilizar o token que você gerou no ponto 4.3 do guia “Passos Rápidos para Publicar um Imóvel de Teste”.
LEAD_ID	string	Não	Identificador de um lead, um valor semelhante a: 6b4aebf8-5570-47b8-9224-c1c177621575.

Nota: Ao consultar os leads, é possível obter na resposta o campo results.leads.id.

A resposta obtida será semelhante à seguinte:

{
    "id": "44115522",
    "item_id": "MLB4037459422",
    "created_at": "2024-02-14T00:00:00Z",
    "contact_type": "whatsapp",
    "external_id": "13864821",
    "status": "active",
    "buyer_id": 1091441589,
    "name": "Test Test",
    "email": "john@example.com",
    "phone": "+55 01 1111-1111"
}

Descrição dos campos

Campo	Tipo de dado	Descrição
id	string	Identificador do lead.
item_id	string	Identificador do item.
created_at	string (data)	Data de criação do lead.
contact_type	string	Tipo de lead.
external_id	string	Identificador externo do lead.
status	string	Status do lead.
buyer_id	número	Identificador do comprador.
name	string	Nome do comprador. Disponível apenas se o acesso for público.
email	string	E-mail do comprador. Disponível apenas se o acesso for público.
phone	string	Telefone do comprador. Disponível apenas se o acesso for público.

Leads de Perguntas

Como mencionado anteriormente, é possível consultar leads específicos de uma publicação da seguinte forma, por exemplo, para perguntas:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/vis/users/$USER_ID/leads/buyers?contact_types=question

Parâmetros

Parâmetro	Tipo	Opcional	Valores
USER_ID	string	Não	ID do vendedor a consultar.
contact_types	string	Não	Tipo de lead a consultar. Os valores possíveis são: whatsapp, question, call e quotation.

Isso retornará as seguintes informações:

{
    "results": [
        {
            "id": 2678328,
            "item_id": "MLA1430828018",
            "name": "John Doe",
            "email": "john@example.com",
            "phone": "+5491198765432",
            "leads": [
                {
                    "id": "6b4aebf8-5570-47b8-9224-c1c177621575",
                    "contact_type": "question",
                    "created_at": "2024-05-14T14:15:39Z",
                    "external_id": "12776297658",
                    "item_id": "MLA1430828018",
                    "buyer_id": 2678328,
                    "status": "active",
                    "sub_status": "answered"
                }
            ]
        }
    ],
    "paging": {
        "offset": 0,
        "limit": 10,
        "total": 1
    },
    "date_from": "2024-05-14",
    "date_to": "2024-05-24"
}

Para obter o texto da pergunta, não é possível fazê-lo consultando o detalhe de um lead. Nesse caso, deve-se consultar a API de perguntas da seguinte forma:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/questions/$QUESTION_ID?api_version=4

Parâmetros

Parâmetro	Tipo	Opcional	Valores
ACCESS_TOKEN	string	Não	Utilize o token gerado no ponto 4.3 do guia “Passos Rápidos para Publicar um Imóvel de Teste”.
QUESTION_ID	string	Não	Corresponde ao `external_id` retornado na resposta anterior.

A resposta será semelhante à seguinte:

{
   "id": 12776297658,
   "seller_id": 179571326,
   "buyer_id": 2678328,
   "item_id": "MLA1430828018",
   "deleted_from_listing": false,
   "suspected_spam": false,
   "status": "ANSWERED",
   "hold": false,
   "text": "Texto da pergunta.",
   "app_id": 8304540643508652,
   "date_created": "2021-02-08T17:51:21.746608612Z",
   "last_updated": "2021-02-08T17:51:29.184950392Z",
   "answer": {
       "text": "",
       "status": "BANNED",
       "date_created": "2021-02-16T14:52:13.580-04:00"
   }
}

Descrição dos campos

Campo	Tipo de dado	Descrição
id	número	Identificador único da pergunta (coincide com o `external_id` do lead).
seller_id	número	Identificador do vendedor que recebeu a pergunta.
buyer_id	número	Identificador do comprador que fez a pergunta.
item_id	string	Identificador do item ao qual a pergunta se refere.
deleted_from_listing	booleano	Indica se a pergunta foi removida do anúncio.
suspected_spam	booleano	Indica se a pergunta é considerada suspeita de spam.
status	string	Status da pergunta.
hold	booleano	Indica se a pergunta está em espera.
text	string	Texto da pergunta.
app_id	número	Identificador do aplicativo de origem da pergunta.
date_created	string (data/hora)	Data e hora da criação da pergunta (formato ISO 8601).
last_updated	string (data/hora)	Data e hora da última atualização (formato ISO 8601).
answer	objeto	Objeto contendo as informações da resposta à pergunta.
answer.text	string	Texto da resposta. Pode estar vazio se o status for "BANNED".
answer.status	string	Status da resposta.
answer.date_created	string (data/hora)	Data e hora da criação da resposta (formato ISO 8601).

Importante:

Se o status da pergunta ou da resposta for "BANNED", será retornado um texto vazio. Utilize o parâmetro api_version=4 para obter a nova estrutura do JSON.
As perguntas com mais de 7 meses sem resposta serão removidas automaticamente.

Para mais informações sobre como interagir com a API de perguntas, consulte: Documentação da API de Perguntas.

Possíveis erros

A seguir, são descritos alguns erros comuns ao consultar leads:

Código de erro 400 - Bad Request

Mensagem: Invalid date range
Motivo: A data inicial é posterior à data final.

{
    "message": "invalid date range",
    "error": "bad_request",
    "status": 400,
    "cause": [
        "start date is greater than end date"
    ]
}

Mensagem: Invalid Start Date
Motivo: Data inicial com formato inválido.

{
    "message": "invalid start date",
    "error": "bad_request",
    "status": 400,
    "cause": [
        "parsing time '2021-01-021': extra text: '1'"
    ]
}

Mensagem: Invalid End Date
Motivo: Data final com formato inválido.

{
    "message": "invalid end date",
    "error": "bad_request",
    "status": 400,
    "cause": [
        "parsing time '2024-01-022': extra text: '2'"
    ]
}

Mensagem: Invalid Format USER_ID
Motivo: Formato do identificador de usuário inválido.

{
    "code": "bad_request",
    "message": "invalid format USER_ID"
}

Mensagem: Invalid Lead Type
Motivo: Tipo de contato inválido.

{
    "message": "invalid lead type",
    "error": "bad_request",
    "status": 400,
    "cause": [
        "invalid lead type: invalid"
    ]
}

Código de erro 403 - Forbidden

Mensagem: Invalid token caller
Motivo: O Access Token não pertence ao vendedor.

{
    "code": "forbidden",
    "message": "invalid token caller"
}

Mensagem: Invalid Token
Motivo: Token inválido ou expirado.

{
    "code": "forbidden",
    "message": "invalid token"
}

Código de erro 404 - Not Found

Mensagem: Lead not found
Motivo: O identificador fornecido não está associado a nenhum lead do usuário.

{
    "code": "not_found",
    "message": "lead not found"
}

Código de erro 409 - Too many requests

Mensagem: Quota Exceeded
Motivo: Foram feitas muitas solicitações. Aguarde antes de tentar novamente.

{
    "code": "too_many_requests",
    "message": "quota exceeded"
}

Leituras recomendadas

Atualizações de versão

Esta seção fornece informações sobre as atualizações da API, incluindo:

Histórico de alterações

Data	Versão	Descrição
08/11/2025	1.0	Publicação inicial
26/01/2026	1.1	Adicionado parâmetro opcional include_guest=true no endpoint "Consultar interessados nos itens do vendedor"