Skip to main content
POST
/
crm
/
v3
/
lists
/
search
cURL
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
}

Documentation Index

Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Supported products

Authorizations

Authorization
string
header
required

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

Body

application/json

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[]

ILS list ids to be included in search results. If not specified, all lists matching other criteria will be included

objectTypeId
string
processingTypes
string[]

List processing types to be included in search results. If not specified, all lists with all processing types will be included.

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 operation

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 May 15, 2026