getClassifiedLeadsByItemId: eBay Leads API

GET/classified_lead/{itemId}

This method returns a seller account's leads generated by the specified classified ad, and includes any contact information that prospective buyers have submitted. Optionally, just those matching specified filter criteria can be returned.

Note: This is a (Limited Release) API available only to select developers approved by business units. For information on how to obtain access to this API in production, please contact eBay support.

Input

Resource URI

GET https://apiz.ebay.com/sell/leads/v1/classified_lead/{itemId}?

startTime=string&

endTime=string&

includeMessages=boolean&

status=string

This method is supported in Sandbox environment. To access the endpoint, just replace the apiz.ebay.com root URI with apiz.sandbox.ebay.com

URI parameters

Parameter	Type	Description
itemId	string	The unique identifier of the listing. Occurrence: Required
startTime	string	Use with endTime to limit the returned leads for the user. Only leads with a start time greater than or equal to the specified date and time will be returned. Note: The startTime and endTime fields can be used independently to filter results. The time stamp must be formatted as an ISO 8601 string, which is based on the 24-hour Universal Coordinated Time (UTC) clock. Format: `[YYYY]-[MM]-[DD]T[hh]:[mm]:[SS]Z` Example: `2025-01-10T15:54:00Z` Occurrence: Optional
endTime	string	Use with startTime to limit the returned leads for the user for active listings. Only leads with a creation date less than or equal to the specified date and time will be returned. Note: The startTime and endTime fields can be used independently to filter results. The time stamp must be formatted as an ISO 8601 string, which is based on the 24-hour Universal Coordinated Time (UTC) clock. Format: `[YYYY]-[MM]-[DD]T[hh]:[mm]:[SS]Z` Example: `2025-01-10T15:54:00Z` Occurrence: Optional
includeMessages	boolean	Include this field and set it to true to retrieve any member messages associated with leads in the memberMessage container (`true` returns messages). Default: `true` Occurrence: Optional
status	string	Include this field if you would only like to retrieve leads where the buyer has answered questions or has not answered questions. If not used, leads with answered questions and unanswered questions are returned. Valid values include: `Answered` `Unanswered` Occurrence: Optional

HTTP request headers

All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.

The table below shows additional HTTP request headers that are either required, conditionally required, or strongly recommended for this method. Other standard HTTP request headers- opens rest request components page (not in this table) can also be used, but they are optional.

Header Type Description

Header	Type	Description
Content-Type	string	This header indicates the format of the request body provided by the client. Its value should be set to application/json. For more information, refer to HTTP request headers. Occurrence: Required
Accept-Encoding	string	This header indicates the compression-encoding algorithms the client accepts for the response. This value should be set to `gzip`. For more information, refer to HTTP request headers. Occurrence: Strongly Recommended

Content-Type

string

This header indicates the format of the request body provided by the client. Its value should be set to application/json.

For more information, refer to HTTP request headers.

Occurrence: Required

Accept-Encoding

string

This header indicates the compression-encoding algorithms the client accepts for the response. This value should be set to gzip.

For more information, refer to HTTP request headers.

Occurrence: Strongly Recommended

OAuth scope

This request requires an access token created with the authorization code grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):

https://api.ebay.com/oauth/api_scope/sell.leads

See OAuth access tokens for more information.

Request payload

This call has no payload.

Request fields

This call has no field definitions.

Output

HTTP response headers

This call has no response headers.

Response payload

Copy complete valid JSON to clipboard

{ /* ClassifiedLead */

"itemId" : "string",

"itemTitle" : "string",

"responses" : [

{ /* ClassifiedLeadResponses */

"additionalInformation" : "string",

"contactInformation" :

{ /* ContactInformation */

"firstName" : "string",

"lastName" : "string",

"phone" : "string",

"postalCode" : "string"

"email" : "string",

"externalEmail" : "string",

"financingAnswer" : "boolean",

"leadFee" :

{ /* LeadFee */

"amount" :

{ /* Amount */

"convertedFromCurrency" : "string",

"convertedFromValue" : "string",

"currency" : "string",

"value" : "string"

"description" : "string"

"leadStatus" : "LeadStatus : [NEW,RESPONDED]",

"memberMessage" :

{ /* MemberMessage */

"memberMessageExchange" : [

{ /* MemberMessageExchange */

"creationDate" : "string",

"question" :

{ /* Question */

"body" : "string",

"messageID" : "integer"

"response" : "string"

}

]

"submittedTime" : "string",

"tradeInMake" : "string",

"tradeInModel" : "string",

"tradeInYear" : "string",

"userId" : "string"

}

]

}

Response fields

Output container/field	Type	Description
itemId	string	The unique identifier of the listing. Occurrence: Always
itemTitle	string	The title of the listing. Max length: 80. Occurrence: Always
responses	array of ClassifiedLeadResponses	An array of the classified lead responses. Occurrence: Conditional
responses.additionalInformation	string	This field shows the first message that was sent from the prospective buyer to the seller. This will be the same content as in the memberMessageExchange.question.body field, if returned. Note: Retrieve the memberMessageExchange container to retrieve the entire exchange between the seller and the prospective buyer (all messages). Occurrence: Conditional
responses.contactInformation	ContactInformation	This container consists of contact information for the prospective buyer. Fields in this container are returned if provided. This container will not be returned if the buyer did not provide any contact information. Occurrence: Conditional
responses.contactInformation.firstName	string	The first name of the prospective buyer. Occurrence: Conditional
responses.contactInformation.lastName	string	The last name of the prospective buyer. Occurrence: Conditional
responses.contactInformation.phone	string	The prospective buyer's primary phone number. Occurrence: Conditional
responses.contactInformation.postalCode	string	The prospective buyer's postal code. Occurrence: Conditional
responses.email	string	Email address for the prospective buyer, if that buyer was logged in to eBay. Occurrence: Conditional
responses.externalEmail	string	Email address for the prospective buyer as entered in the lead form on the View Item page. Provides a way for sellers to contact prospective buyers who choose not to log in to eBay. This applies to only eBay Motors and eBay Motors categories. Occurrence: Conditional
responses.financingAnswer	boolean	Boolean that indicates if a prospective buyer answered whether or not they would like financing. Entered on the lead form on the View Item page. Applies to eBay Motors and Motors categories only. Occurrence: Conditional
responses.leadFee	LeadFee	A container that returns the amount charged for this pay per lead contact, in the item's site local currency. Occurrence: Always
responses.leadFee.amount	Amount	A container that returns the amount charged for the lead service with currency information. Occurrence: Conditional
responses.leadFee.amount.convertedFromCurrency	string	A three-letter ISO 4217 code that indicates the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency. Occurrence: Conditional
responses.leadFee.amount.convertedFromValue	string	The monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field. Occurrence: Conditional
responses.leadFee.amount.currency	string	A three-letter ISO 4217 code that indicates the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field. Occurrence: Always
responses.leadFee.amount.value	string	The monetary amount, in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency. Occurrence: Always
responses.leadFee.description	string	An explanation of the special fee charged. Occurrence: Always
responses.leadStatus	LeadStatus	The enumeration value in this field indicates whether or not the seller has responded to the lead, or if this is new. Occurrence: Conditional
responses.memberMessage	MemberMessage	Contains any mail message content shared between the seller and prospective buyer. Only returned if the includeMessages boolean is `true`. Occurrence: Always
responses.memberMessage.memberMessageExchange	array of MemberMessageExchange	An array that provides detailed information about a member-to-member message. Occurrence: Conditional
responses.memberMessage.memberMessageExchange.creationDate	string	Date the message was created. Returned if the parent container is returned. Occurrence: Conditional
responses.memberMessage.memberMessageExchange.question	Question	Contains all the information about the question being asked. Returned if the parent container is returned. Occurrence: Conditional
responses.memberMessage.memberMessageExchange.question.body	string	Content of the message is input into this string field. Occurrence: Conditional
responses.memberMessage.memberMessageExchange.question.messageID	integer	The unique identifier of the message. Occurrence: Conditional
responses.memberMessage.memberMessageExchange.response	string	An answer to the question. Contains the body of the seller's response message, if sent. Occurrence: Conditional
responses.submittedTime	string	Date and time (in GMT) that the lead was submitted. Occurrence: Always
responses.tradeInMake	string	The make of the vehicle the prospective buyer would like to trade in. Entered on the lead form on the View Item page. Applies to eBay Motors and Motors categories only. Occurrence: Conditional
responses.tradeInModel	string	The model of the vehicle the prospective buyer would like to trade in. Entered on the lead form on the View Item page. Applies to eBay Motors and Motors categories only. Occurrence: Conditional
responses.tradeInYear	string	The year of the vehicle the prospective buyer would like to trade in. Entered on the lead form on the View Item page. Applies to eBay Motors and Motors categories only. Occurrence: Conditional
responses.userId	string	The eBay user ID of the user who is interested in the seller's item. Occurrence: Conditional

HTTP status codes

This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.

Status	Meaning
200	OK
204	No Content
401	Unauthorized
500	Internal Server Error

Error codes

For more on errors, plus the codes of other common errors, see Handling errors.

Code	Domain	Category	Meaning
350000	API_LEADS	APPLICATION	There was a problem with an eBay internal system or process. Contact eBay developer support for assistance.
352002	API_LEADS	REQUEST	Invalid Item ID. Please provide a valid item ID.
352003	API_LEADS	REQUEST	Invalid UTC Time. Please provide a valid UTC time in the format YYYY-MM-DDTHH:MM:SSZ.
352004	API_LEADS	REQUEST	Invalid Date. Date has to be in the past.
352005	API_LEADS	REQUEST	Invalid Date Range. End time should be greater than start time.
352006	API_LEADS	REQUEST	Invalid status. Please provide a valid status value (Answered/Unanswered).
352007	API_LEADS	REQUEST	Invalid value for includeMessages. Please provide a valid boolean value (true/false).

Warnings

This call has no warnings.

Samples

New to making API calls? Please see Making a Call.

Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.

Sample 1: Returns all leads generated for the specified classified ad listing based on the criteria

This call retrieves the generated leads based on the criteria for the specified ID.

Input

This method does not use a request payload. This sample retrieves all leads between the start and end time, with all buyer details and includes the messages exchanged between seller and buyer for the specified lead (itemId). This sample returns the leads that the buyer has not answered.

GEThttps://apiz.ebay.com/sell/leads/v1/classified_lead/2**********5?startTime=2024-07-13T15:54:00Z&endTime=2025-01-17T06:41:06Z&includeMessages=true

Output

If the call is successful, an array of lead responses for the specified classified ad listing is returned.

{
    "itemId": "2**********5",
    "itemTitle": "1947 Pontiac Streamliner ",
    "responses": [
        {
            "additionalInformation": "Test lead",
            "contactInformation": {
                "phone": "8********0",
                "postalCode": "8***1",
                "firstName": "L**a",
                "lastName": "L****r"
            },
            "email": "--",
            "submittedTime": "2025-01-06T18:00:12Z",
            "memberMessage": {
                "memberMessageExchange": [
                    {
                        "question": {
                            "body": "Test lead",
                            "messageID": "5*******19"
                        },
                        "creationDate": "2025-01-06T18:00:13Z"
                    },
                    {
                        "response": "Testing response from seller",
                        "creationDate": "2025-01-17T06:38:16Z"
                    }
                ]
            },
            "leadStatus": "RESPONDED",
            "leadFee": {
                "amount": {
                    "currency": "USD",
                    "value": "0.0"
                },
                "description": "Lead fee."
            },
            "externalEmail": "l********r@g*******m",
            "financingAnswer": false
        }
    ]
}