getAllClassifiedLeads: eBay Leads API | eBay Developers Program

GET/classified_lead

This method retrieves leads for all of the seller's active classified ad listings. 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?

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
startTime	string	Use with endTime to limit the returned leads for the user. Only leads for active listings with a creation date 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. 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	Boolean that indicates whether to return mail messages for this lead in a memberMessage container (`true` returns messages). If omitted, no messages for this lead will be returned (same as when set to `false`). Default: false Occurrence: Optional
status	string	The enumeration value in this field will indicate whether or not a question has been answered. 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

{ /* ClassifiedLeadsListResponse */

"classifiedLeads" : [

{ /* 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"

}

]

}

"totalItems" : "integer",

"totalLeads" : "integer"

}

Response fields

Output container/field	Type	Description
classifiedLeads	array of ClassifiedLead	An array of leads for the seller's active classified ad listings. Occurrence: Conditional
classifiedLeads.itemId	string	The unique identifier of the listing. Occurrence: Always
classifiedLeads.itemTitle	string	The title of the listing. Max length: 80. Occurrence: Always
classifiedLeads.responses	array of ClassifiedLeadResponses	An array of the classified lead responses. Occurrence: Conditional
classifiedLeads.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
classifiedLeads.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
classifiedLeads.responses.contactInformation.firstName	string	The first name of the prospective buyer. Occurrence: Conditional
classifiedLeads.responses.contactInformation.lastName	string	The last name of the prospective buyer. Occurrence: Conditional
classifiedLeads.responses.contactInformation.phone	string	The prospective buyer's primary phone number. Occurrence: Conditional
classifiedLeads.responses.contactInformation.postalCode	string	The prospective buyer's postal code. Occurrence: Conditional
classifiedLeads.responses.email	string	Email address for the prospective buyer, if that buyer was logged in to eBay. Occurrence: Conditional
classifiedLeads.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
classifiedLeads.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
classifiedLeads.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
classifiedLeads.responses.leadFee.amount	Amount	A container that returns the amount charged for the lead service with currency information. Occurrence: Conditional
classifiedLeads.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
classifiedLeads.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
classifiedLeads.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
classifiedLeads.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
classifiedLeads.responses.leadFee.description	string	An explanation of the special fee charged. Occurrence: Always
classifiedLeads.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
classifiedLeads.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
classifiedLeads.responses.memberMessage.memberMessageExchange	array of MemberMessageExchange	An array that provides detailed information about a member-to-member message. Occurrence: Conditional
classifiedLeads.responses.memberMessage.memberMessageExchange.creationDate	string	Date the message was created. Returned if the parent container is returned. Occurrence: Conditional
classifiedLeads.responses.memberMessage.memberMessageExchange.question	Question	Contains all the information about the question being asked. Returned if the parent container is returned. Occurrence: Conditional
classifiedLeads.responses.memberMessage.memberMessageExchange.question.body	string	Content of the message is input into this string field. Occurrence: Conditional
classifiedLeads.responses.memberMessage.memberMessageExchange.question.messageID	integer	The unique identifier of the message. Occurrence: Conditional
classifiedLeads.responses.memberMessage.memberMessageExchange.response	string	An answer to the question. Contains the body of the seller's response message, if sent. Occurrence: Conditional
classifiedLeads.responses.submittedTime	string	Date and time (in GMT) that the lead was submitted. Occurrence: Always
classifiedLeads.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
classifiedLeads.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
classifiedLeads.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
classifiedLeads.responses.userId	string	The eBay user ID of the user who is interested in the seller's item. Occurrence: Conditional
totalItems	integer	The total number of listings returned. Occurrence: Always
totalLeads	integer	The total number of leads returned for all listings. Occurrence: Always

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.
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 by all classified ads listings based on the criteria

This call retrieves an array of leads based on the criteria.

Input

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

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

Output

If the call is successful, an array of leads is returned.

{
    "totalItems": 6,
    "totalLeads": 7,
    "classifiedLeads": [
        {
            "itemId": "2*********55",
            "itemTitle": "2016 Chevrolet Traverse LT Sport Utility 4D",
            "responses": [
                {
                    "additionalInformation": "test contact seller",
                    "contactInformation": {
                        "phone": "4********0",
                        "postalCode": "9***9",
                        "firstName": "A********d",
                        "lastName": "B**r"
                    },
                    "email": "t*******************@g*******m",
                    "submittedTime": "2024-12-26T18:36:30Z",
                    "userId": "t******************2",
                    "memberMessage": {
                        "memberMessageExchange": [
                            {
                                "question": {
                                    "body": "test contact seller",
                                    "messageID": "5*******19"
                                },
                                "creationDate": "2024-12-26T18:36:30Z"
                            },
                            {
                                "question": {
                                    "body": "test contact seller",
                                    "messageID": "5*******29"
                                },
                                "creationDate": "2024-12-26T18:36:30Z"
                            }
                        ]
                    },
                    "leadStatus": "NEW",
                    "tradeInMake": "Honda",
                    "tradeInModel": "Civic",
                    "tradeInYear": "2008",
                    "leadFee": {
                        "amount": {
                            "currency": "USD",
                            "value": "0.0"
                        },
                        "description": "Lead fee."
                    },
                    "externalEmail": "t*******************@g*******m",
                    "financingAnswer": false
                }
            ]
        },
        {
            "itemId": "2**********6",
            "itemTitle": "1947 Pontiac Streamliner ",
            "responses": [
                {
                    "additionalInformation": "test contact seller",
                    "address": {
                        "phone": "4********0",
                        "postalCode": "9***9",
                        "firstName": "A********d",
                        "lastName": "B**r"
                    },
                    "email": "t*******************@g*******m",
                    "submittedTime": "2024-12-26T20:27:59Z",
                    "userId": "t******************2",
                    "memberMessage": {
                        "memberMessageExchange": [
                            {
                                "question": {
                                    "body": "test contact seller",
                                    "messageID": "5*******19"
                                },
                                "creationDate": "2024-12-26T20:27:59Z"
                            },
                            {
                                "question": {
                                    "body": "test contact seller",
                                    "messageID": "5*******29"
                                },
                                "creationDate": "2024-12-26T20:17:26Z"
                            }
                        ]
                    },
                    "leadStatus": "NEW",
                    "leadFee": {
                        "amount": {
                            "currency": "USD",
                            "value": "0.0"
                        },
                        "description": "Lead fee."
                    },
                    "externalEmail": "t*******************@g*******m",
                    "financingAnswer": true
                }
            ]
        },
        {
            "itemId": "2*********95",
            "itemTitle": "1947 Pontiac Streamliner ",
            "responses": [
                {
                    "additionalInformation": "Test lead",
                    "contactInformation": {
                        "phone": "8********0",
                        "postalCode": "84061",
                        "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*********@g*******m",
                    "financingAnswer": false
                }
            ]
        },
        {
            "itemId": "2*********50",
            "itemTitle": "2002 Ford Thunderbird ",
            "responses": [
                {
                    "additionalInformation": "test swu 2",
                    "contactInformation": {
                        "phone": "1********0",
                        "postalCode": "91604",
                        "firstName": "E***k",
                        "lastName": "N****o"
                    },
                    "email": "--",
                    "submittedTime": "2025-01-13T19:33:10Z",
                    "memberMessage": {
                        "memberMessageExchange": [
                            {
                                "question": {
                                    "body": "test swu 2",
                                    "messageID": "5*******19"
                                },
                                "creationDate": "2025-01-13T19:33:10Z"
                            }
                        ]
                    },
                    "leadStatus": "NEW",
                    "leadFee": {
                        "amount": {
                            "currency": "USD",
                            "value": "0.0"
                        },
                        "description": "Lead fee."
                    },
                    "externalEmail": "e******@ebay.com",
                    "financingAnswer": false
                },
                {
                    "additionalInformation": "SWU Test",
                    "contactInformation": {
                        "phone": "1********0",
                        "postalCode": "91604",
                        "firstName": "E***k",
                        "lastName": "N****o"
                    },
                    "email": "--",
                    "submittedTime": "2025-01-13T19:18:32Z",
                    "memberMessage": {
                        "memberMessageExchange": [
                            {
                                "question": {
                                    "body": "SWU Test",
                                    "messageID": "5*******19"
                                },
                                "creationDate": "2025-01-13T19:18:33Z"
                            }
                        ]
                    },
                    "leadStatus": "NEW",
                    "leadFee": {
                        "amount": {
                            "currency": "USD",
                            "value": "0.0"
                        },
                        "description": "Lead fee."
                    },
                    "externalEmail": "e******@e******m",
                    "financingAnswer": false
                }
            ]
        },
        {
            "itemId": "2*********01",
            "itemTitle": "1938 Plymouth Sedan Delivery",
            "responses": [
                {
                    "additionalInformation": "adadas",
                    "contactInformation": {
                        "phone": "4********0",
                        "postalCode": "9***9",
                        "firstName": "A********d",
                        "lastName": "B**r"
                    },
                    "email": "t*******************@g*******m",
                    "submittedTime": "2024-12-26T18:48:41Z",
                    "userId": "t******************2",
                    "memberMessage": {
                        "memberMessageExchange": [
                            {
                                "question": {
                                    "body": "adadas",
                                    "messageID": "5*******19"
                                },
                                "creationDate": "2024-12-26T18:48:41Z"
                            }
                        ]
                    },
                    "leadStatus": "NEW",
                    "leadFee": {
                        "amount": {
                            "currency": "USD",
                            "value": "0.0"
                        },
                        "description": "Lead fee."
                    },
                    "externalEmail": "t*******************@g*******m",
                    "financingAnswer": true
                }
            ]
        },
        {
            "itemId": "2*********63",
            "itemTitle": "2012 Ford F-550 Super Duty XL 12' stakebed w liftgate(1600 LB)",
            "responses": [
                {
                    "additionalInformation": "i want to test this",
                    "contactInformation": {
                        "phone": "3********0",
                        "postalCode": "2***2",
                        "firstName": "test",
                        "lastName": "man"
                    },
                    "email": "--",
                    "submittedTime": "2025-01-14T12:14:18Z",
                    "memberMessage": {
                        "memberMessageExchange": [
                            {
                                "question": {
                                    "body": "i want to test this",
                                    "messageID": "5*******19"
                                },
                                "creationDate": "2025-01-14T12:14:19Z"
                            },
                            {
                                "response": "Response from seller",
                                "creationDate": "2025-01-15T06:01:09Z"
                            }
                        ]
                    },
                    "leadStatus": "RESPONDED",
                    "tradeInYear": "Any",
                    "leadFee": {
                        "amount": {
                            "currency": "USD",
                            "value": "0.0"
                        },
                        "description": "Lead fee."
                    },
                    "externalEmail": "t***@**********m",
                    "financingAnswer": true
                }
            ]
        }
    ]
}