For a given portal, return a list of leads according to various criteria.
This API method has several optional parameters. You can use any of these in any combination in order to have a more specific, and thus faster, search. See below for the parameter available to you.
Inside each lead is some basic lead information, followed by an array of conversion events (zero or more), followed by lead deletion logs and lead to customer conversion fields.
Inside each conversion event are form submissions (zero or more), and inside each form submission are the fields from the form, one at a time.
| Required Parameters | How to use | Description |
|---|---|---|
| HubSpot OAuth Access Token | access_token=X - Used in the request URL | The HubSpot API key for the portal that you're making the call for. |
| Optional Parameters | How to use | Description |
|---|---|---|
| Search | &search=X - Used in the request URL | Basic lead search that will return multiple matched leads. An optional string value that is used to search several basic lead fields: first name, last name, email address, and company name. The default value for this parameter is an empty string, meaning return all leads. |
| Sort | &sort=X - Used in the request URL | An optional string value that specifies the lead attribute on which you wish to sort. The most commonly-used options here are "firstName", "lastName", "email", "address", "phone", "insteredAt", "lastModifiedAt", "closedAt", among others. |
| Sort Direction | &dir=X - Used in the request URL | You can specify the sort direction for the returned leads. Acceptable values are asc for ascending sort, and desc for descending sort, just like SQL |
| Max | &max=X - Used in the request URL | The maximum number of leads to return. The default number returned is 10. The maximum is 100. |
| Offset | &offset=X - Used in the request URL | Optional integer offset into the list of leads matching the search request. This parameter is very useful for pagination (used in conjunction with the "max" parameter). For instance, you can first get 100 leads back from the API, then include the "&offset=100" to get a list of the next 100 leads, etc...The default value for this parameter is zero. |
| Start Time | &startTime=X - Used in the request URL | Unix timestamp in milliseconds (milliseconds since 1/1/1970 00:00:00 GMT). The returned list will have only leads inserted into the database after this time. The default value for this parameter is zero, i.e. the epoch, to include all leads |
| Stop Time | &stopTime=X - Used in the request URL | Unix timestamp in milliseconds (milliseconds since 1/1/1970 00:00:00 GMT). This timestamp will restrict the most recent end of the returned leads list. The default value for this parameter is right now. |
| Time Pivot | &timePivot=X - Used in the request URL | The field on which the startTime and stopTime paramaters should be applied, must be one of the following fields: "insertedAt", "firstConvertedAt", "lastConvertedAt", "lastModifiedAt", "closedAt" |
| Exclude Conversion Events | &excludeConversionEvents=X - Used in the request URL | Set to true to exclude all items in the leadConversionEvents collection from the API results. This will increase performance for larger lists, with the tradeoff of reduced information being about your leads. |
| Opt Out | &optOut=X - Used in the request URL | Boolean value that you can set to "true" to include only leads that have unsubscribed from lead nurturing. The default value, false, includes all leads. |
| Eligible for Email | ?eligibleForEmail=X - Used in the request URL | Boolean value that you can set to "true" to include only leads eligible for email marketing. The default value, false, includes all leads. |
| Bounced | ?bounced=X - Used in the request URL | Boolean value that you can set to "true" to include only leads that HubSpot has tried to email, and the email bounced. The default value, false, includes all leads. |
| Is Not Imported | ?isNotImported=X - Used in the request URL | Boolean value that you can set to "true" to include only web leads. The default value, false, includes both imported and web leads. |
| Include Deleted | ?includeDeleted=X - Used in the request URL | Boolean value that you can set to "true" to include leads that have been deleted. The default value, false, returns only leads that have not been deleted. |
| Lead GUIDs | ?guids[0]=X - Used in the request URL | A HubSpot lead's GUID. You may set more than one of these in a single query to retrieve multiple leads at once (e.g. &guids[0]=8a41f2f22906b93a012906b9438f0008 and &guids[1]=8a41f2f22913e087012913e0afce000d to get these 2 leads returned to you). If you provide more than 100 guids to by retrieved in a single query, you will receive a 413 Request Entity Too Large HTTP error, please only try to hydrate 100 or less guids at a time. |
Example URL: https://api.hubapi.com/leads/v1/list?access_token=demooooo-oooo-oooo-oooo-oooooooooooo&max=1
Example JSON output. This example is displaying a single lead from the HubSpot demo portal, along with the conversion values from the single conversion event that this lead has gone through:
[
{
"address": "",
"analyticsDetails": {
"allViewsImported": true,
"countsModifiedAt": 1279853227000,
"firstVisitAt": 1275710855000,
"id": "8a41f2f22906b93a012906b9438f0008",
"lastPageViewAt": 1275710855000,
"lastVisitAt": 1275710855000,
"leadGuid": "8a41f2f22906b93a012906b9438f0008",
"leadId": 830918,
"pageViewCount": 2,
"portalId": 62515,
"userToken": "13067f6bfbd542098793fda0542a93f9",
"visitCount": 2
},
"city": "",
"closedAt": 1272997000000,
"company": "",
"country": "",
"crmDetails": {
"annualRevenue": 0,
"closeProbability": 1,
"crmType": 1,
"estimatedRevenue": 0,
"id": "8a41f2f22906b93a012906b9438f0008",
"nextAction": "",
"nextActionAssignedTo": 0,
"nextActionAssignedToEmail": "",
"nextActionDue": 0,
"numEmployees": 0,
"status": "Open"
},
"customerStatusModifiedAt": 0,
"eligibleForEmail": true,
"email": "info@hubspot.com",
"emailBounced": false,
"emailOptOut": false,
"fax": "",
"firstCampaign": "",
"firstName": "HubSpot",
"firstRefDomain": "",
"firstReferrer": "http://www.hubspot.com/",
"firstURL": "http://demo.hubapi.com/",
"firstVisitSetAt": 1275718091660,
"foundVia": "Referrals",
"fullFoundViaString": "Referrals - hubspot.com",
"guid": "8a41f2f22906b93a012906b9438f0008",
"id": "8a41f2f22906b93a012906b9438f0008",
"imported": false,
"industry": "",
"insertedAt": 1275718091660,
"ipAddress": "184.73.15.169",
"isCustomer": true,
"isDeleted": false,
"jobTitle": "",
"lastConvertedAt": 1275718058000,
"lastModifiedAt": 1320349394338,
"lastName": "Internet Marketing Specialists",
"leadConversionEvents": [
{
"convertDate": 1275718058000,
"formGuid": "fcbd0c1834a14534adfc1f0197801048",
"formId": 25349,
"formName": "Contact Us",
"formSubmissionValues": [
{
"conversionGuid": "15e857315cce44448c8abd9fb33aa651",
"convertDate": 1275718058000,
"fieldLabel": "First Name",
"fieldName": "FirstName",
"fieldValue": "HubSpot",
"formGuid": "fcbd0c1834a14534adfc1f0197801048",
"formId": 25349,
"formName": "Contact Us",
"id": 767892282,
"leadGuid": "8a41f2f22906b93a012906b9438f0008",
"portalId": 62515
},
{
"conversionGuid": "15e857315cce44448c8abd9fb33aa651",
"convertDate": 1275718058000,
"fieldLabel": "Last Name",
"fieldName": "LastName",
"fieldValue": "Internet Marketing Specialists",
"formGuid": "fcbd0c1834a14534adfc1f0197801048",
"formId": 25349,
"formName": "Contact Us",
"id": 767892292,
"leadGuid": "8a41f2f22906b93a012906b9438f0008",
"portalId": 62515
},
{
"conversionGuid": "15e857315cce44448c8abd9fb33aa651",
"convertDate": 1275718058000,
"fieldLabel": "Email (we will keep your email completely private)",
"fieldName": "Email",
"fieldValue": "info@hubspot.com",
"formGuid": "fcbd0c1834a14534adfc1f0197801048",
"formId": 25349,
"formName": "Contact Us",
"id": 767892312,
"leadGuid": "8a41f2f22906b93a012906b9438f0008",
"portalId": 62515
},
{
"conversionGuid": "15e857315cce44448c8abd9fb33aa651",
"convertDate": 1275718058000,
"fieldLabel": "Message",
"fieldName": "Message",
"fieldValue": "This is a sample lead, but if you want help getting more leads, give us a call at 1-888-HUBSPOT, ext. #1",
"formGuid": "fcbd0c1834a14534adfc1f0197801048",
"formId": 25349,
"formName": "Contact Us",
"id": 767892332,
"leadGuid": "8a41f2f22906b93a012906b9438f0008",
"portalId": 62515
}
],
"guid": "15e857315cce44448c8abd9fb33aa651",
"id": "15e857315cce44448c8abd9fb33aa651",
"leadGuid": "8a41f2f22906b93a012906b9438f0008",
"pageName": "Landing Pages",
"pageType": "Form",
"pageUrl": "http://demohubapi.web6.hubspot.com/landing-pages/Default.aspx?RewriteStatus=1",
"portalId": 62515
}
],
"leadCustomerStatusModifyLogs": [
{
"id": 4135752,
"insertedAt": 1303305845158,
"previousState": false
}
],
"leadDeleteLogs": [],
"leadId": 830918,
"leadJsonLink": "https://api.hubapi.com/leads/v1/lead/8a41f2f22906b93a012906b9438f0008",
"leadLink": "https://app.hubspot.com/leads/app/lead?portalId=62515&guid=8a41f2f22906b93a012906b9438f0008",
"leadNurturingActive": true,
"leadNurturingCampaignId": 77244,
"message": "This is a sample lead, but if you want help getting more leads, give us a call at 1-888-HUBSPOT, ext. #1",
"numConversionEvents": 1,
"phone": "",
"portalId": 62515,
"publicLeadLink": "https://app.hubspot.com/leads/public/leadDetails?portalId=62515&leadToken=KmAEjOwsiFAa0h1fn6ce%2Bw%3D%3D",
"rawScore": 140,
"salutation": "",
"score": 99.96,
"sourceId": 2,
"sourceValue1": "hubspot.com",
"sourceValue2": "",
"sourceValueModifiedAt": 1320349394338,
"state": "",
"twitterHandle": "",
"userToken": "13067f6bfbd542098793fda0542a93f9",
"website": "",
"zip": ""
}
]
Here an explanation and definition of some of the lead fields that get returned to you. Again, to update certain fields, please see the Update Lead method.
Editable or Writable Fields:
Non-editable (non-writable) Fields:
HTTP Methods:
GET
Response Format:
json
Requires Authentication?
Yes
Rate Limited?
Headers