Skip to main content
POST
/
crm
/
v3
/
lists
/
search
Search Lists
curl --request POST \
  --url https://api.hubapi.com/crm/v3/lists/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "additionalProperties": [
    "hs_list_size_week_delta"
  ],
  "count": 100,
  "offset": 0,
  "query": "Test"
}
'
{
  "hasMore": false,
  "lists": [
    {
      "additionalProperties": {
        "hs_last_record_added_at": "1695938616824",
        "hs_list_reference_count": "0",
        "hs_list_size": "59",
        "hs_list_size_week_delta": "-10"
      },
      "createdAt": "2023-09-28T22:03:17.998Z",
      "createdById": "1",
      "filtersUpdatedAt": "2023-09-28T22:03:17.998Z",
      "listId": "123",
      "listVersion": 1,
      "name": "Test list",
      "objectTypeId": "0-1",
      "processingStatus": "COMPLETE",
      "processingType": "SNAPSHOT",
      "updatedAt": "2023-09-28T22:03:37.005Z",
      "updatedById": "1"
    }
  ],
  "offset": 1,
  "total": 1
}

Supported products

Requires one of the following products or higher.
Marketing HubMarketing Hub -Free
Sales HubSales Hub -Free
Service HubService Hub -Free
Content HubContent Hub -Free
Data HubData Hub -Free

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Body

application/json

The IDs of the records to add and/or remove from the list.

The request object used for searching through lists.

​
additionalProperties
string[]
required

The property names of any additional list properties to include in the response. Properties that do not exist or that are empty for a particular list are not included in the response.

By default, all requests will fetch the following properties for each list: hs_list_size, hs_last_record_added_at, hs_last_record_removed_at, hs_folder_name, and hs_list_reference_count.

​
offset
integer<int32>
required

Value used to paginate through lists. The offset provided in the response can be used in the next request to fetch the next page of results. Defaults to 0 if no offset is provided.

​
count
integer<int32>

The number of lists to include in the response. Defaults to 20 if no value is provided. The max count is 500.

​
listIds
string[]

The listIds that will be used to filter results by listId. If values are provided, then the response will only include results that have a listId in this array.

If no value is provided, or if an empty list is provided, then the results will not be filtered by listId.

​
processingTypes
string[]

The processingTypes that will be used to filter results by processingType. If values are provided, then the response will only include results that have a processingType in this array.

If no value is provided, or if an empty list is provided, then results will not be filtered by processingType.

Valid processingTypes are: MANUAL, SNAPSHOT, or DYNAMIC.

​
query
string

The query that will be used to search for lists by list name. If no query is provided, then the results will include all lists.

​
sort
string

Sort field and order

Response

Successful response

The response object with the list search hits and additional information regarding pagination.

​
hasMore
boolean
required

Whether or not there are more results to page through.

​
lists
object[]
required

The lists that matched the search criteria.

​
offset
integer<int32>
required

Value to be passed in a future request to paginate through list search results.

​
total
integer<int32>
required

The total number of lists that match the search criteria.

Last modified on December 16, 2025