{ "openapi": "3.1.0", "info": { "title": "Classified Leads API", "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.", "contact": { "name": "eBay Inc," }, "license": { "name": "eBay API License Agreement", "url": "https://developer.ebay.com/join/api-license-agreement" }, "version": "v1.0.0" }, "servers": [ { "url": "https://apiz.ebay.com{basePath}", "description": "Production", "variables": { "basePath": { "default": "/sell/leads/v1" } } } ], "security": [ {} ], "paths": { "/classified_lead": { "get": { "tags": [ "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(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.

", "operationId": "getAllClassifiedLeads", "parameters": [ { "name": "endTime", "in": "query", "description": "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 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", "required": false, "schema": { "type": "string" } }, { "name": "includeMessages", "in": "query", "description": "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

", "required": false, "schema": { "type": "string" } }, { "name": "startTime", "in": "query", "description": "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", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "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:
", "required": false, "schema": { "type": "string" } }, { "name": "Accept-Encoding", "in": "header", "description": "This header indicates the compression-encoding algorithms the client accepts for the response. This value should be set to gzip.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClassifiedLeadsListResponse" } } } }, "400": { "description": "Bad Request", "x-response-codes": { "errors": { "352005": { "domain": "API_LEADS", "category": "REQUEST", "description": "Invalid Date Range. End time should be greater than start time." }, "352004": { "domain": "API_LEADS", "category": "REQUEST", "description": "Invalid Date. Date has to be in the past." }, "352007": { "domain": "API_LEADS", "category": "REQUEST", "description": "Invalid value for includeMessages. Please provide a valid boolean value (true/false)." }, "352006": { "domain": "API_LEADS", "category": "REQUEST", "description": "Invalid status. Please provide a valid status value (Answered/Unanswered)." }, "352003": { "domain": "API_LEADS", "category": "REQUEST", "description": "Invalid UTC Time. Please provide a valid UTC time in the format YYYY-MM-DDTHH:MM:SSZ." } } } }, "500": { "description": "Internal Server Error", "x-response-codes": { "errors": { "350000": { "domain": "API_LEADS", "category": "APPLICATION", "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance." } } } }, "401": { "description": "Unauthorized" }, "204": { "description": "No Content" } }, "security": [ { "api_auth": [ "https://api.ebay.com/oauth/api_scope/sell.leads" ] } ] } }, "/classified_lead/{itemId}": { "get": { "tags": [ "classified_lead" ], "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(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.

", "operationId": "getClassifiedLeadsByItemId", "parameters": [ { "name": "endTime", "in": "query", "description": "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", "required": false, "schema": { "type": "string" } }, { "name": "includeMessages", "in": "query", "description": "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", "required": false, "schema": { "type": "string" } }, { "name": "itemId", "in": "path", "description": "The unique identifier of the listing.", "required": true, "schema": { "type": "string" } }, { "name": "startTime", "in": "query", "description": "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", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "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:
", "required": false, "schema": { "type": "string" } }, { "name": "Accept-Encoding", "in": "header", "description": "This header indicates the compression-encoding algorithms the client accepts for the response. This value should be set to gzip.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClassifiedLead" } } } }, "400": { "description": "Bad Request", "x-response-codes": { "errors": { "352005": { "domain": "API_LEADS", "category": "REQUEST", "description": "Invalid Date Range. End time should be greater than start time." }, "352004": { "domain": "API_LEADS", "category": "REQUEST", "description": "Invalid Date. Date has to be in the past." }, "352007": { "domain": "API_LEADS", "category": "REQUEST", "description": "Invalid value for includeMessages. Please provide a valid boolean value (true/false)." }, "352006": { "domain": "API_LEADS", "category": "REQUEST", "description": "Invalid status. Please provide a valid status value (Answered/Unanswered)." }, "352003": { "domain": "API_LEADS", "category": "REQUEST", "description": "Invalid UTC Time. Please provide a valid UTC time in the format YYYY-MM-DDTHH:MM:SSZ." }, "352002": { "domain": "API_LEADS", "category": "REQUEST", "description": "Invalid Item ID. Please provide a valid item ID." } } } }, "500": { "description": "Internal Server Error", "x-response-codes": { "errors": { "350000": { "domain": "API_LEADS", "category": "APPLICATION", "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance." } } } }, "401": { "description": "Unauthorized" }, "204": { "description": "No Content" } }, "security": [ { "api_auth": [ "https://api.ebay.com/oauth/api_scope/sell.leads" ] } ] } } }, "components": { "schemas": { "Amount": { "type": "object", "required": ["currency", "value"], "properties": { "convertedFromCurrency": { "type": "string", "description": "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": { "type": "string", "description": "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": { "type": "string", "description": "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": { "type": "string", "description": "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." } }, "description": "This type provides the monetary amount of the special fee." }, "ClassifiedLead": { "type": "object", "required": ["itemId", "itemTitle"], "properties": { "itemId": { "type": "string", "description": "The unique identifier of the listing." }, "itemTitle": { "type": "string", "description": "The title of the listing.

Maximum length: 80" }, "responses": { "type": "array", "description": "An array of the classified lead responses.", "items": { "$ref": "#/components/schemas/ClassifiedLeadResponses" } } }, "description": "This type contains the classified lead ID and other information." }, "ClassifiedLeadResponses": { "type": "object", "required": ["leadFee", "memberMessage", "submittedTime"], "properties": { "additionalInformation": { "type": "string", "description": "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": { "description": "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.", "$ref": "#/components/schemas/ContactInformation" }, "email": { "type": "string", "description": "Email address for the prospective buyer, if that buyer was logged in to eBay." }, "externalEmail": { "type": "string", "description": "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": { "type": "boolean", "description": "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": { "description": "A container that returns the amount charged for this pay-per-lead contact in the item's site local currency.", "$ref": "#/components/schemas/LeadFee" }, "leadStatus": { "description": "The enumeration value in this field indicates whether or not the seller has responded to the lead or if this is new.", "$ref": "#/components/schemas/LeadStatus" }, "memberMessage": { "description": "Contains any mail message content shared between the seller and prospective buyer.

Only returned if the includeMessages boolean is true.", "$ref": "#/components/schemas/MemberMessage" }, "submittedTime": { "type": "string", "description": "Date and time (in GMT) that the lead was submitted." }, "tradeInMake": { "type": "string", "description": "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": { "type": "string", "description": "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": { "type": "string", "description": "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": { "type": "string", "description": "The eBay user ID of the user who is interested in the seller's item." } }, "description": "This type provides classified lead responses, including any contact information that prospective buyers have submitted." }, "ClassifiedLeadsListResponse": { "type": "object", "required": ["totalItems", "totalLeads"], "properties": { "classifiedLeads": { "type": "array", "description": "An array of leads for the seller's active classified ad listings.", "items": { "$ref": "#/components/schemas/ClassifiedLead" } }, "totalItems": { "type": "integer", "description": "The total number of listings returned.", "format": "int32" }, "totalLeads": { "type": "integer", "description": "The total number of leads returned for all listings.", "format": "int32" } }, "description": "This type contains an array of the seller's active classified ad listings and the total number of items and leads." }, "ContactInformation": { "type": "object", "properties": { "firstName": { "type": "string", "description": "The first name of the prospective buyer." }, "lastName": { "type": "string", "description": "The last name of the prospective buyer." }, "phone": { "type": "string", "description": "The prospective buyer's primary phone number." }, "postalCode": { "type": "string", "description": "The prospective buyer's postal code." } }, "description": "This type consists of contact information for the prospective buyer." }, "Error": { "type": "object", "properties": { "category": { "type": "string", "description": "Identifies the type of erro." }, "domain": { "type": "string", "description": "Name for the primary system where the error occurred. This is relevant for application errors." }, "errorId": { "type": "integer", "description": "A unique number to identify the error.", "format": "int32" }, "inputRefIds": { "type": "array", "description": "An array of request elements most closely associated to the error.", "items": { "type": "string" } }, "longMessage": { "type": "string", "description": "A more detailed explanation of the error." }, "message": { "type": "string", "description": "Information on how to correct the problem, in the end user's terms and language where applicable." }, "outputRefIds": { "type": "array", "description": "An array of request elements most closely associated to the error.", "items": { "type": "string" } }, "parameters": { "type": "array", "description": "An array of name/value pairs that describe details the error condition. These are useful when multiple errors are returned.", "items": { "$ref": "#/components/schemas/ErrorParameter" } }, "subdomain": { "type": "string", "description": "Further helps indicate which subsystem the error is coming from. System subcategories include: Initialization, Serialization, Security, Monitoring, Rate Limiting, etc." } }, "description": "This type defines the fields that can be returned in an error." }, "ErrorParameter": { "type": "object", "properties": { "name": { "type": "string", "description": "The object of the error." }, "value": { "type": "string", "description": "The value of the object." } } }, "LeadFee": { "type": "object", "required": ["description"], "properties": { "amount": { "description": "A container that returns the amount charged for the lead service with currency information.", "$ref": "#/components/schemas/Amount" }, "description": { "type": "string", "description": "An explanation of the special fee charged." } }, "description": "This type returns the amount charged for the lead service." }, "LeadStatus": { "type": "object", "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.", "enum": [ "NEW", "RESPONDED" ] }, "MemberMessage": { "type": "object", "properties": { "memberMessageExchange": { "type": "array", "description": "An array that provides detailed information about a member-to-member message.", "items": { "$ref": "#/components/schemas/MemberMessageExchange" } } }, "description": "This type defines the field containing any mail message content shared between the seller and prospective buyer." }, "MemberMessageExchange": { "type": "object", "properties": { "creationDate": { "type": "string", "description": "This is the date the message was created. It is returned if the parent container is returned." }, "question": { "description": "This contains all the information about the question being asked. It is returned if the parent container is returned.", "$ref": "#/components/schemas/Question" }, "response": { "type": "string", "description": "This is an answer to the question. It contains the body of the seller's response message, if sent." } }, "description": "This type defines the fields containing detailed information about a member-to-member message." }, "Question": { "type": "object", "properties": { "body": { "type": "string", "description": "This is the content of the message." }, "messageID": { "type": "integer", "description": "This is the unique identifier of the message.", "format": "int32" } }, "description": "This type contains the body and ID of the question." } }, "securitySchemes": { "api_auth": { "type": "oauth2", "description": "The security definitions for this API. Please check individual operations for applicable scopes.", "flows": { "authorizationCode": { "authorizationUrl": "https://auth.ebay.com/oauth2/authorize", "tokenUrl": "https://api.ebay.com/identity/v1/oauth2/token", "scopes": { "https://api.ebay.com/oauth/api_scope/sell.leads" : "" } } } }, "bearerAuth": { "type": "http", "scheme": "bearer" } } } }