Interested persons

The resource /vis/users/$USER_ID/leads/buyers allows the buyer to obtain contact details of buyers interested in their listings.

Check interested users in the seller’s

Now, the seller can check all the contact details of the interested users, with the possibility of paginating them by means of the offset parameter, which indicates the position of the first item to fetch, and the limit parameter, which indicates the maximum number of items to fetch. In addition, the details can be filtered by a specific time period, using the "dateFrom" and "dateTo" parameters. For a more specific search, the channels parameter can be used, which represents the type of contact to return. Also, the "has_credit_line" parameter allows the system to determine whether to display only those users who have an active credit line.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/vis/users/$USER_ID/leads/buyers?offset=$OFFSET&limit=$LIMIT&dateFrom=$DATE_FROM&dateTo=$DATE_TO&hasCreditLine=$HAS_CREDIT_LINE&channels=$CHANNELS

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/vis/users/806525693/leads/buyers?offset=0&limit=10&dateFrom=2023-06-15&dateTo=2023-06-22&hasCreditLine=true&channels=credit,question,whatsapp

Input values

Attribute	Type of detail	Description	Required	Default value
userID	int	Seller identifier.	Yes	-
offset	int	Position of the first element of the list of items.	No	0
limit	int	Number of maximum elements of the list of items.	No	10
dateFrom	string	Search start date. Allowed formats: 2006-01-02T15:04:05Z 2006-01-02T15:04:05 2006-01-02	No	7 days before the current date.
dateTo	string	Search end date. Allowed formats: 2006-01-02T15:04:05Z 2006-01-02T15:04:05 2006-01-02	No	Current date.
channels	string	Type of contacts to provide. If it's not sent, all types of contacts are provided.	No	All channels.
offset	int	Position of the first item in the list of items.	No	0
has_credit_line	boolean	Indicates whether the interested buyer has a credit line. If it's not sent, buyers with and without credit lines are provided.	No	-

Response fields

• results: contains list of results.
• results.id: buyer identifier.
• results.item_id: item identifier.
• results.name: buyer identifier. Only if access is public.
• results.email: buyer’s email. Only if access is public.
• results.phone: buyer’s phone number. Only if access is public.
• results.leads: contains a list of the leads generated by the buyer.
• leads.uuid: lead identifier.
• leads.external_id: external lead identifier.
• leads.channel: type of lead.
• leads.item_id: item identifier.
• leads.created_at: lead creation date.
• leads.has_credit_line: indicates if the buyer has a credit line.
• leads.status: status of the lead.
• paging: contains pagination information.
• paging.offset: position of the first element to provide.
• paging.limit: number of maximum elements per page.
• paging.total: number of total elements.
• date_from: results start date.
• date_to: results end date.

Response:

{
  "results": [
    {
      "id": 2678328,
      "name": "John Doe",  
      "email": "jhon@example.com",  
      "phone": "+5491198765432",  
      "item_id": "MLA1430828018",
      "leads": [
        {
          "uuid": "6b4aebf8-5570-47b8-9224-c1c177621575",
          "channel": "question",
          "item_id": "MLA1430828018",
          "has_credit_line": true,
          "created_at": "2023-07-12T22:17:02Z",
          "external_id": "12776297658",
          "status": "active"
        }
      ]
    }
  ],
  "paging": {
    "total": 1,
    "offset": 0,
    "limit": 20
  },
  "date_from": "2021-07-12T22:17:02Z",
  "date_to": "2021-07-12T22:17:02Z"
}

Possible errors

Errors in the search of interested users.

Error_code	Tipo	Message of the error	Reasons
400	Bad Request	{ "message": "invalid date range", "error": "bad_request", "status": 400, "cause": [ "start date is greater than end date" ] }	The start date is after the end date of the search.
400	Bad Request	{ "message": "invalid start date", "error": "bad_request", "status": 400, "cause": [ "parsing time \"2021-01-021\": extra text: \"1\"" ] }	Start date with invalid format.
400	Bad Request	{ "message": "invalid end date", "error": "bad_request", "status": 400, "cause": [ "parsing time \"2024-01-022\": extra text: \"2\"" ] }	End date with invalid format.
400	Bad Request	{ "message": "invalid has credit line", "error": "bad_request", "status": 400, "cause": [ "strconv.ParseBool: parsing \"2021-01-021\": invalid syntax" ] }	Indicator parameter of credit line with invalid format.
400	Bad Request	{ "code": "bad_request", "message": "invalid format userID" }	User ID with invalid format.
400	Bad Request	{ "message": "error decoding search params", "error": "bad_request", "status": 400, "cause": [ "schema: invalid path \"channel\"" ] }	Invalid parameter.
400	Bad Request	{ "message": "invalid lead type", "error": "bad_request", "status": 400, "cause": [ "invalid lead type: invalid " ] }	Invalid contact type.
400	Forbidden	{ "code": "forbidden", "message": "invalid token caller" }	Access token doesn’t belong to the seller.
400	Forbidden	{ "blocked_by": "PolicyAgent", "path": "/v1/users/806525693/leads/buyers?scope=test-public", "code": "PA_UNAUTHORIZED_RESULT_FROM_POLICIES", "status": 403, "message": "At least one policy returned UNAUTHORIZED." }	Access to the endpoint without access to the token.
400	Forbidden	{ "code": "forbidden", "message": "invalid token" }	Invalid or expired access token.
400	Too many requests	{ "code":"too_many_requests", "message":"quota exceeded" }	Too many requests. Please wait a moment before trying again.

Get details of a Lead

When Mercado Libre notifies the creation of a new lead related to interested users, it does so by mentioning the ID in the message. To obtain the details you have to use that identifier in the resource "/vis/leads/{$LEAD_ID}", which will give you the corresponding details.

Request:

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

Exmaple:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/vis/leads/3f2dedf2-dfbd-4981-a726-40b13aa172ff

Entry values

Attribute	Type of detail	Description	Required	Default value
leadID	string	Lead identifier.	Yes	-

Response fields

• id: lead identifier.
• contact_type: type of lead.
• item_id: item identifier.
• buyer__has_credit_line: indicates if the buyer has a credit line.
• created_at: lead creation date.
• external_id: external lead identifier.
• status: status of the lead.
• buyer_id: buyer identifier.
• name: buyer name. Only if access is public.
• email: buyer email. Only if access is public.
• phone: buyer’s phone number. Only if access is public.

Response: HTTP 200

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

Possible errors

Errors in the search of the detail of a lead.

Error_code	Tipo	Message of the error	Reasons
400	Bad Request	{ "code": "bad_request", "message": "missing lead_id" }	Incorrect or non-existent identifier.
400	Bad Request	{ "code": "bad_request", "message": "invalid callerID" }	The caller ID provided is not the right one.
400	Bad Request	{ "code": "bad_request", "message": "invalid clientID" }	The client ID provided isn’t available or isn’t correct.
403	Forbidden	{ "code": "forbidden", "message": "invalid token caller" }	Access token doesn’t belong to the buyer.
403	Forbidden	{ "blocked_by": "PolicyAgent", "path": "/vis/leads/142536", "code": "PA_UNAUTHORIZED_RESULT_FROM_POLICIES", "status": 403, "message": "At least one policy returned UNAUTHORIZED." }	Access to the endpoint without access to the token.
403	Forbidden	{ "code": "forbidden", "message": "invalid token" }	Invalid or expired access token.
404	Not Found	{ "code": "not_found", "message": "lead not found" }	The identifier provided is not associated with any user lead.
409	Too many requests	{ "code":"too_many_requests", "message":"quota exceeded" }	Too many requests. Please wait a moment before trying again.