What’s Changing?

A new Lists API has been added to the HubSpot API catalog.  This API will allow for a more rich and comprehensive experience for developers removing several of the limitations of the Contact Lists API.

Why is this changing?

Lists have evolved over the years to support more advanced filtering criteria such as custom behavioral events.  Lists also support multiple object types including Contacts, Deals and Companies.  The Contact Lists API has not scaled in concert with Lists and, starting today, we are working to change that with the introduction of the V3 Lists API.  

What do I need to know?

1. The API functionality will be released in 2 phases starting on September 27, 2023.
   1. Release 1:  Includes the ability to add or remove records to existing lists, add all records from one list to another, and view records from an existing list.
   2. Release 2: Will include the ability to create and delete lists and will be available in the 4th quarter of this year.  There will be a subsequent changelog post when it is available.
2. The API is no longer restricted to contacts lists.  It will be available for usage with lists for  contacts, deals, companies, and custom objects.
3. Full documentation of the endpoints can be found in our developer documentation.

We have created a dedicated slack channel in the HubSpot Developer slack group to encourage discussion around this beta.  You can find it by joining the slack group and searching for #lists-api-v3.