---
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: 1.0
api_name: leads_api
api_type: REST
api_group: sell/leads_api
source_url:
  html: https://developer.ebay.com/develop/api/sell/leads_api
  md: https://developer.ebay.com/develop/api/sell/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 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`.

### 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`.

## 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.

## 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-07-08T04:29:18.276Z*