Skip to main content

Postman collection

Lists (now called segments) are a collection of records of the same object that can be used for record segmentation, filtering, and grouping to serve your business needs. The v3 Lists API allows you to create, edit, and fetch lists, as well as convert active lists into static lists.
A list consists of a list definition and list memberships:
  • List definition: stores essential information about the list.
  • List memberships: mappings between the list and object record.
The legacy v1 lists API will be sunset on April 30th, 2026. If you’re using the v1 lists API, review the guide to transition to the v3 API.

​
List processing types

There are three types of list processing types: MANUAL, DYNAMIC, and SNAPSHOT.
  • MANUAL: this processing type indicates that object records can only be added to or removed from the list via manual actions by the user or API call. There is no list processing or list membership management done in the background by HubSpot’s systems. This type of list is helpful for when you need a set list of records that won’t change unless manually updated.
  • DYNAMIC: this processing type gives the possibility to specify list filters to match records that will become list members. This type of list is processed in the background by HubSpot to ensure that the list only contains records that match the list’s filters. Whenever a record changes, it is reevaluated against the list’s filters and either added to or removed from it. This type of list is helpful for when you want to keep a running list that you expect to change over time.
  • SNAPSHOT: list filters are specified at the time of list creation. After initial processing is completed, records can only be added to or removed from the list by manual actions. This type of list is helpful for when you want to create a list of records based on specific criteria, but don’t want that list to change automatically after initial processing.

​
Create a list

To create a list, make a POST request to /crm/v3/lists. In the request body, you must include the following fields: name, objectTypeId, and processingType. The filterBranch parameter is optional, and can be included to create branching logic for DYNAMIC and SNAPSHOT type lists. Learn more about configuring list filters and branches. For example, the following request body would create a new static list of contacts: 
{
  "name": "My static list",
  "objectTypeId": "0-1",
  "processingType": "MANUAL"
}
Once created, a listId (the ILS list ID) will be generated. This ID is used for future updates and modifications. The following is an example response with the ILS list ID highlighted: 
{
  "list": {
    "listId": "611",
    "listVersion": 1,
    "createdAt": "2026-02-02T16:13:48.146Z",
    "updatedAt": "2026-02-02T16:13:48.146Z",
    "filtersUpdatedAt": "2026-02-02T16:13:48.146Z",
    "processingStatus": "COMPLETE",
    "createdById": "9586504",
    "updatedById": "9586504",
    "processingType": "MANUAL",
    "objectTypeId": "0-1",
    "name": "My static list",
    "listPermissions": {
      "teamsWithEditAccess": [],
      "usersWithEditAccess": []
    },
    "membershipSettings": {
      "membershipTeamId": null,
      "includeUnassigned": null
    }
  }
}

​
Retrieve lists

Depending on your use case, there are multiple ways to retrieve lists. A list can be retrieved via the lists API by its name and object or by its ILS list ID. When retrieving lists, include a query parameter of includeFilters=true to return list filter definitions in the response. To retrieve lists by other criteria (e.g., processing type), you can use the search API.

​
Retrieve by list name

To retrieve a list by name, make a GET request to /crm/v3/lists/object-type-id/{objectTypeId}/name/{listName}. The objectTypeId is the ID that corresponds to the type of object stored by the list. See the full list of object type IDs. For example, to retrieve the contact list created above, make a GET request to /crm/v3/lists/object-type-id/0-1/name/My%20static%20list.

​
Retrieve by ILS List ID

A list’s ILS ID is returned in the listId field when a new list is created. To find an existing list’s ILS ID, you can either:
  • Navigate to the lists (segments) tool in HubSpot, then hover over the list and click Details. Learn more about viewing lists.
  • Search for a list by other criteria, then view the listId in the response.
To retrieve lists by ILS ID:
  • To retrieve an individual list by ILS list ID, make a GET request to /crm/v3/lists/{listId}.
  • To retrieve multiple lists by ILS list ID, make a GET request to /crm/v3/lists and include a listIds query parameter for each list. For example: /crm/v3/lists?listIds=940&listIds=938.

​
Retrieve by searching list details

You can search for lists by other criteria by making a POST request to /crm/v3/lists/search. In the request body, specify the criteria that you want to search by.
  • To search for lists that contain specific words in their name, include the query field.
  • To search for lists of a specific processing type, include a processingTypes array with each of the processing types you want to search by.
  • To search for lists of a specific object, include the objectTypeId field, with the type ID value for the object (e.g., 0-1 for contacts).
For example, to search for contact static lists that contain “HubSpot” in the name, your request body would look like: 
{
  "query": "HubSpot",
  "processingTypes": ["MANUAL"],
  "objectTypeId": "0-1"
}

​
Update lists

You can update a list’s name and its filters via the lists API.

​
Update list name

To update a list’s name, make a PUT request to /crm/v3/lists/{listId}/update-list-name with the listName query parameter. If the list with the provided ILS list ID exists, then its name will be updated to the provided listName. The listName must be unique amongst all other public lists in the account. You can also include a query parameter of includeFilters=true to return list filter definitions in the response. For example, to change a list’s name (with the ILS ID 612) to “January Event Contacts List” and return filters, the request URL would be: /crm/v3/lists/612/update-list-name?listName=January%20Event%20Contacts%20List&includeFilters=true. Expand the section below to review an example of the expected response.

​
Update a list filter branch

To update a DYNAMIC list’s filter branches, make a PUT request to /crm/v3/lists/{listId}/update-list-filters. In the request body, include the updated filter branch definition. This definition will replace the existing definition, so make sure to include any filters you want to keep from the previous definition. Once the filter branch is updated, the list will begin processing its new memberships. For example, your list includes a filter based on contact’s Likelihood to close (hs_predictivecontactscore_v2) that you want to keep. To add filters to include contacts with a value for email who also opted into certain email subscriptions, your request body would look like: 
{
  "filterBranch": {
    "filterBranchType": "OR",
    "filterBranches": [
      {
        "filterBranchType": "AND",
        "filters": [
          {
            "filterType": "PROPERTY",
            "operation": {
              "operationType": "NUMBER",
              "operator": "IS_GREATER_THAN_OR_EQUAL_TO",
              "value": 12
            },
            "property": "hs_predictivecontactscore_v2"
          },
          {
            "filterType": "PROPERTY",
            "operation": {
              "operationType": "ALL_PROPERTY",
              "operator": "IS_KNOWN"
            },
            "property": "email"
          },
          {
            "acceptedStatuses": [
              "OPT_IN"
            ],
            "filterType": "EMAIL_SUBSCRIPTION",
            "subscriptionIds": [
              "81537745",
              "321981152"
            ]
          }
        ]
      }
    ]
  }
}

​
Delete and restore a list

To delete a list, make a DELETE request to /crm/v3/lists/{listId}. Once deleted, lists can be restored within 90 days of deletion by making a PUT request to /crm/v3/lists/{listID}/restore. Lists deleted more than 90 days ago cannot be restored.

​
Manage list membership

To view and manage records included in a list, you can use the /memberships/ endpoints below. List membership endpoints that update memberships can only be used on MANUAL or SNAPSHOT list processing types. DYNAMIC lists will add and remove records based on the filter criteria set. You cannot use list membership endpoints to update your list. Instead, edit the list’s filters or the record you want to add or remove.

​
Retrieve records with list memberships

To retrieve records with list memberships, you’ll need to make two calls: one to retrieve the records, then another to retrieve their list memberships. First, make a POST request to /crm/v3/objects/{objectTypeId}/search with the object for which you want to search records (e.g.,0-1 for contacts). You can add filters to specify the records you want.
  • To retrieve recently created records, filter by createdate.
  • To retrieve recently updated records, filter by lastmodifieddate.
You can add properties to retrieve more details about the records as needed. For example, to search for contacts edited after May 31, 2025: 
{
  "properties": [
    "firstname",
    "lastname",
    "email",
    "hs_object_id",
    "createdate",
    "lastmodifieddate"
  ],
  "filterGroups": [
    {
      "filters": [
        {
          "propertyName": "lastmodifieddate",
          "operator": "GT",
          "value": "2025-05-31"
        }
      ]
    }
  ]
}
Next, use the object endpoint to retrieve the membership details for the records individually or in bulk. From your search request, use record id values to retrieve list membership details. To retrieve an individual record’s memberships, make a GET request to /crm/v3/lists/records/{objectTypeId}/{recordId}/memberships. For example, to retrieve an individual contact’s memberships, your request URL would look like /crm/v3/lists/records/0-1/1234567/memberships. Your response will look like: 
{
  "results": [
    {
      "listId": "76",
      "listVersion": 1,
      "isPublicList": true,
      "firstAddedTimestamp": "2025-07-28T13:42:08.595Z",
      "lastAddedTimestamp": "2025-07-28T13:42:08.595Z"
    },
    {
      "listId": "78",
      "listVersion": 1,
      "isPublicList": true,
      "firstAddedTimestamp": "2025-07-28T13:42:08.595Z",
      "lastAddedTimestamp": "2025-07-28T13:42:08.595Z"
    },
    {
      "listId": "493",
      "listVersion": 1,
      "isPublicList": false,
      "firstAddedTimestamp": "2024-07-23T19:40:36.192Z",
      "lastAddedTimestamp": "2024-07-23T19:40:36.192Z"
    },
    {
      "listId": "541",
      "listVersion": 1,
      "isPublicList": true,
      "firstAddedTimestamp": "2025-04-21T14:01:43.475Z",
      "lastAddedTimestamp": "2025-04-21T14:01:43.475Z"
    },
    {
      "listId": "492",
      "listVersion": 1,
      "isPublicList": false,
      "firstAddedTimestamp": "2024-07-23T19:36:11.890Z",
      "lastAddedTimestamp": "2024-07-23T19:36:11.890Z"
    }
  ]
}
To retrieve multiple records’ memberships, make a POST request to /crm/v3/lists/records/memberships/batch/read. In the request, include the objectTypeId value of the object for which you’re retrieving records (e.g., 0-1 for contacts) and the id values for the records. For example, to retrieve memberships for contacts 12345 and 67890, your request would look like: 
{
  "inputs": [
    {
      "objectTypeId": "0-1",
      "recordId": "12345"
    },
    {
      "objectTypeId": "0-1",
      "recordId": "101112"
    }
  ]
}

​
View records in an existing list

To view all records in an existing list, make a GET request to /crm/v3/lists/{listId}/memberships. This returns all members of a list ordered by recordId.

​
Add records to an existing list

To add records to an existing list, make a PUT request to /crm/v3/lists/{listId}/memberships/add with a list of record IDs in the request body. For example, your request body would look like: 
[
  "55555",
  "69876",
  "487888",
  "46999874"
]

​
Remove records from an existing list

To remove all records from an existing list, make a DELETE request to /crm/v3/lists/{listId}/memberships. This will not delete the list from your account, but the list will contain no records. To remove specific records from an existing list, make a PUT request to /crm/v3/lists/{listId}/memberships/remove with a list of record IDs in the request body. For example, your request body would look like: 
[
  "12345",
  "55986",
  "489756"
]

​
Add and remove records in the same request

To both add records to and remove records from a list at the same time, make a PUT request to /crm/v3/lists/{listId}/memberships/add-and-remove. In the request body, include the recordIdsToAdd and recordIdsToRemove fields with the IDs of records to add and remove. For example, your request body would look like: 
{
  "recordIdsToAdd": [
    "123",
    "456",
    "789"
  ],
  "recordIdsToRemove": [
    "654",
    "5555"
  ]
}

​
Add records from one list to another

To add all records from one list to another list, make a PUT request to /crm/v3/lists/{listId}/memberships/add-from/{sourceListId}. The listId is the list to add the records to and the sourceListId is the list to retrieve records from. You can move a limit of 100,000 records at a time.

​
Convert lists from active to static

You can convert existing active lists into static lists by scheduling the conversion for a specific date or based on inactivity. You can use the lists endpoints to schedule conversions, retrieve scheduled or past conversions, and delete scheduled conversions.

​
Schedule or update a list conversion

To schedule a conversion or update an existing scheduled conversion, make a PUT request to /crm/v3/lists/{listId}/schedule-conversion. In the request body, include one of the following conversionType values and the type’s related fields:
  • CONVERSION_DATE: schedules the conversion for a specific date. Include year, month, and day fields to specify the desired date. This date must be in the future.
  • INACTIVITY: schedules the conversion if the list hasn’t been active for a set amount of time, based on when the last record was added or removed. Include the timeUnit field to specify the unit of time (DAY, WEEK, or MONTH) and the offset field to specify the amount of time after which the list is considered inactive. Only one timeUnit can be specified and the offset value must be positive.
For example, to schedule an active list to be converted to a static list on January 31, 2025, your request would look like the following: 
{
  "conversionType": "CONVERSION_DATE",
  "year": 2025,
  "month": 1,
  "day": 31
}
To schedule an active list to be converted to a static list after five days of inactivity, your request would look like the following: 
{
  "conversionType": "INACTIVITY",
  "timeUnit": "DAY",
  "offset": 5
}

​
Retrieve a list conversion

To retrieve information about a list’s conversion, make a GET request to /crm/v3/lists/{listId}/schedule-conversion. The response will include the requestedConversionTime object with the conversionType ​and the relevant fields for that type. If the list was already converted, the convertedAt field will be returned with the timestamp of the conversion. For example, for a list that completed a conversion, your response would look similar to the following: 
{
  "listId": "35",
  "requestedConversionTime": {
    "conversionType": "CONVERSION_DATE",
    "year": 2025,
    "month": 1,
    "day": 1
  },
  "convertedAt": "2025-01-01T05:20:34.002Z"
}

​
Delete a scheduled list conversion

To delete a conversion, make a DELETE request to /crm/v3/lists/{listId}/schedule-conversion. If the conversion does not exist, a 404 will be returned.
Last modified on February 2, 2026