---
title: Leads API
description: "The **Leads API** lets sellers return leads generated by their Classified Ad and includes any contact information that prospective buyers have submitted. A seller can retrieve leads for items listed under their own seller account for a specified marketplace optionally filtered by specified search criteria. Use this resource to retrieve sales-lead information for lead-generating classified ad listings. **Note:** This is a [![Limited Release](/cms/img/docs/partners-api.svg \"Limited Release\")(Limited Release)](/develop/guides-v2/using-ebay-restful-apis#versioning-and-the-api-lifecycle) 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. #### Scope restrictions The following scope supports retrieving the details of leads: `https://api.ebay.com/oauth/api_scope/sell.leads`"
api_version: v1.0.0
api_name: leads_api
api_type: REST
api_group: leads/api
source_url:
  html: https://developer.ebay.com/develop/api/leads/api
  md: https://developer.ebay.com/develop/api/leads/api.md
---

# Leads API API

The **Leads API** lets sellers return leads generated by their Classified Ad and includes any contact information that prospective buyers have submitted. A seller can retrieve leads for items listed under their own seller account for a specified marketplace optionally filtered by specified search criteria. Use this resource to retrieve sales-lead information for lead-generating classified ad listings.

**Note:** This is a [![Limited Release](/cms/img/docs/partners-api.svg "Limited Release")(Limited Release)](/develop/guides-v2/using-ebay-restful-apis#versioning-and-the-api-lifecycle) 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.

#### Scope restrictions

The following scope supports retrieving the details of leads:

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

## API Information

**Title:** Classified Leads API
**Version:** v1.0.0
**Description:** The Leads API allows sellers to retrieve sales leads, including prospective buyer contact information, generated by their Classified Ad listings. Sellers can retrieve all leads for items under their account or filter by specific criteria, utilizing the classified\_lead resource for accessing this crucial buyer interest data.
**Base Path:** /sell/leads/v1

## API Methods

The following API methods are available:

### getAllClassifiedLeads

#### GET /classified_lead
**Description:** 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](/cms/img/docs/partners-api.svg "Limited Release")(Limited Release)](https://developer.ebay.com/develop/guides-v2/using-ebay-restful-apis#versioning-and-the-api-lifecycle) 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.
**Parameters:**
- **endTime** (string)
  - Use with **startTime** to limit the number of 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](https://www.iso.org/iso-8601-date-and-time-format.html) 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`
- **includeMessages** (string)
  - 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
- **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](https://www.iso.org/iso-8601-date-and-time-format.html) 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`
- **status** (string)
  - The enumeration value in this field will indicate whether or not a question has been answered. If not used, leads with answered questions and unanswered questions are returned. Valid values include:  

*   `Answered`
*   `Unanswered`
- **Accept-Encoding** (string)
  - This header indicates the compression-encoding algorithms the client accepts for the response. This value should be set to `gzip`.
**OAuth scope**

This request requires an access token created with the **Client Credentials 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):

**Required Scopes:**

**Client Credentials Grant:**

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


### getClassifiedLeadsByItemId

#### GET /classified_lead/{itemId}
**Description:** 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](/cms/img/docs/partners-api.svg "Limited Release")(Limited Release)](https://developer.ebay.com/develop/guides-v2/using-ebay-restful-apis#versioning-and-the-api-lifecycle) 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.
**Parameters:**
- **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](https://www.iso.org/iso-8601-date-and-time-format.html) 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`
- **includeMessages** (string)
  - 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**: `true`
- **itemId** (string) *required*
  - The unique identifier of the listing.
- **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](https://www.iso.org/iso-8601-date-and-time-format.html) 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`
- **status** (string)
  - The enumeration value in this field will indicate whether or not a question has been answered. If not used, leads with answered questions and unanswered questions are returned. Valid values include:  

*   `Answered`
*   `Unanswered`
- **Accept-Encoding** (string)
  - This header indicates the compression-encoding algorithms the client accepts for the response. This value should be set to `gzip`.
**OAuth scope**

This request requires an access token created with the **Client Credentials 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):

**Required Scopes:**

**Client Credentials Grant:**

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


## Error Codes

The following error codes may be returned by this API:

### REQUEST Errors

#### 352003 - API_LEADS
**Description:** Invalid UTC Time. Please provide a valid UTC time in the format YYYY-MM-DDTHH:MM:SSZ.

#### 352004 - API_LEADS
**Description:** Invalid Date. Date has to be in the past.

#### 352005 - API_LEADS
**Description:** Invalid Date Range. End time should be greater than start time.

#### 352006 - API_LEADS
**Description:** Invalid status. Please provide a valid status value (`Answered`/`Unanswered`).

#### 352007 - API_LEADS
**Description:** Invalid value for **includeMessages**. Please provide a valid boolean value (`true`/`false`).

#### 352002 - API_LEADS
**Description:** Invalid Item ID. Please provide a valid item ID.

### APPLICATION Errors

#### 350000 - API_LEADS
**Description:** There was a problem with an eBay internal system or process. Contact eBay developer support for assistance.

## Types

### Amount
**Description:** This type provides the monetary amount of the special fee.
**Type:** object

**Properties:**
- **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.
- **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.
- **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.
- **value** (string)
  - The monetary amount in the currency specified in 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.

### ClassifiedLead
**Description:** This type contains the classified lead ID and other information.
**Type:** object

**Properties:**
- **itemId** (string)
  - The unique identifier of the listing.
- **itemTitle** (string)
  - The title of the listing.  
  
**Maximum length:** 80
- **responses** (array)
  - An array of the classified lead responses.

### ClassifiedLeadResponses
**Description:** This type provides classified lead responses, including any contact information that prospective buyers have submitted.
**Type:** object

**Properties:**
- **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).
- **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.
- **email** (string)
  - Email address for the prospective buyer, if that buyer was logged in to eBay.
- **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 only to eBay Motors and eBay Motors categories.
- **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. This applies only to eBay Motors and Motors categories.
- **leadFee** (LeadFee)
  - A container that returns the amount charged for this pay-per-lead contact in the item's site local currency.
- **leadStatus** (LeadStatus)
  - The enumeration value in this field indicates whether or not the seller has responded to the lead or if this is new.
- **memberMessage** (MemberMessage)
  - Contains any mail message content shared between the seller and prospective buyer.  
  
Only returned if the **includeMessages** boolean is `true`.
- **submittedTime** (string)
  - Date and time (in GMT) that the lead was submitted.
- **tradeInMake** (string)
  - The make of the vehicle the prospective buyer would like to trade in. This is entered on the lead form on the **View Item** page. This applies only to eBay Motors and eBay Motors categories.
- **tradeInModel** (string)
  - The model of the vehicle the prospective buyer would like to trade in. This is entered on the lead form on the **View Item** page. This applies only to eBay Motors and eBay Motors categories.
- **tradeInYear** (string)
  - The year of the vehicle the prospective buyer would like to trade in. This is entered on the lead form on the **View Item** page. This applies only to eBay Motors and eBay Motors categories.
- **userId** (string)
  - The eBay user ID of the user who is interested in the seller's item.

### ClassifiedLeadsListResponse
**Description:** This type contains an array of the seller's active classified ad listings and the total number of items and leads.
**Type:** object

**Properties:**
- **classifiedLeads** (array)
  - An array of leads for the seller's active classified ad listings.
- **totalItems** (integer)
  - The total number of listings returned.
- **totalLeads** (integer)
  - The total number of leads returned for all listings.

### ContactInformation
**Description:** This type consists of contact information for the prospective buyer.
**Type:** object

**Properties:**
- **firstName** (string)
  - The first name of the prospective buyer.
- **lastName** (string)
  - The last name of the prospective buyer.
- **phone** (string)
  - The prospective buyer's primary phone number.
- **postalCode** (string)
  - The prospective buyer's postal code.

### LeadFee
**Description:** This type returns the amount charged for the lead service.
**Type:** object

**Properties:**
- **amount** (Amount)
  - A container that returns the amount charged for the lead service with currency information.
- **description** (string)
  - An explanation of the special fee charged.

### LeadStatus
**Description:** This enumerated type is used to indicate whether or not the seller has responded to the lead. | - **NEW**: The enumeration value in this field indicates there is a new response to the lead. - **RESPONDED**: The enumeration value in this field indicates that the seller has responded to the lead.
**Type:** object

### MemberMessage
**Description:** This type defines the field containing any mail message content shared between the seller and prospective buyer.
**Type:** object

**Properties:**
- **memberMessageExchange** (array)
  - An array that provides detailed information about a member-to-member message.

### MemberMessageExchange
**Description:** This type defines the fields containing detailed information about a member-to-member message.
**Type:** object

**Properties:**
- **creationDate** (string)
  - This is the date the message was created. It is returned if the parent container is returned.
- **question** (Question)
  - This contains all the information about the question being asked. It is returned if the parent container is returned.
- **response** (string)
  - This is an answer to the question. It contains the body of the seller's response message, if sent.

### Question
**Description:** This type contains the body and ID of the question.
**Type:** object

**Properties:**
- **body** (string)
  - This is the content of the message.
- **messageID** (integer)
  - This is the unique identifier of the message.

## Rate Limits

See [API Call Limits](https://developer.ebay.com/develop/get-started/api-call-limits) on the eBay Developer Program.

## Resources

### Documentation

- [eBay Developer Program](https://developer.ebay.com/)
- [API Documentation](https://developer.ebay.com/develop/api/)
- [SDKs and Widgets](https://developer.ebay.com/develop/sdks-and-widgets)
- [Developer Community Forum](https://community.ebay.com/t5/Developer-Groups/ct-p/developergroup)

### Tools

- [API Explorer](https://developer.ebay.com/my/api_test_tool)
- [GraphQL Explorer](https://developer.ebay.com/my/graphql_explorer)

### Support

- [Developer Support](https://developer.ebay.com/support/)
- [API Status](https://developer.ebay.com/support/api-status)
- [Release Notes](https://developer.ebay.com/develop/api/release_notes/)

---
*Generated on 2026-04-13T15:03:09.679Z*