Create Dynamic Lists With the New Lists API

Hey y', all, It's Brooke with HubSpot Academy. Today I'm going to talk about the exciting new list API. We've just launched version 3 of this awesome API. Lists are an integral part of your CRM segmenting your CRM records for more targeted use cases. V3 of the list API gives you the ability to create lists for multiple different cross CRM types, including contacts, companies, deals, and more. It also allows you to create complex list filters for dynamic lists using multiple different logic operators such as and, and, or. This API replaces the version 1 of the List API, which was only connected to Contacts. The V1 API will be sunsetted in May 2025. Now let's check out how you can use the new V3 list API to to create both static and active lists. So here I am in our beta version of our developer documentation on our list page. This will give you an overview of everything that you can do with the list, including specific things that you need to know in order to use your list properly. The most important thing to highlight here is the list processing types. There are three types of list processing types. Manual, dynamic, and Snapshot. So a manual processing type indicates that object records can only be added to or removed from the list via manual actions. Dynamic Lists is a processing type that gives the possibility to specify filters to match records that will become list members and finally snapshots. Filters are specified at the time of the list creation, but after that initial processing is completed, records can only be added to or removed from the list by manual actions. Now let's go over and look at the different API endpoints. So up at the top click on API and Reference and then API endpoints. Then in the left hand sidebar click on CRM and then click on Lists. Now here you'll see all of the different API endpoints you can call for the lists. For this one we are going to go ahead and in the right hand sidebar click on the Create list and and it has this really great flag for all of the different API endpoints to tell you the different CRUD methods that you're going to do. So this one will be a post method. So now you can actually test your calls within the developer documentation if you have OAuth or if you have a private app key. I'm going to go ahead and create a local note app first. So what I'm actually going to do is I'm going to press on this, copy all and this will copy all of this code to my clipboard so I can use it within My Node app, I'm going to go over to my VS code, inside of my VS code, I'm going to go into my terminal and I'm going to just go ahead and create a new folder using Make Dir. We're going to just call this the List API and then we're going to CD into our Lists API. So now I'm just going to initialize a new Node app by using NPM Init. We're going to keep the package name list API version 1.0 description. We'll leave that blank right now. Entry point is going to be our index JS file. No test command, no git repository keywords, author license will be fine. And then we'll click on enter. So now inside of our List API folder, we now have our package JSON. So for this one, we're going to use the HubSpot API client to help us with using the endpoints. So the API client just is a wrapper for our API endpoints so that you can call them within Node in an easier fashion. So we're going to do npm install at HubSpot/API dash client and this will go ahead and download our API client with locally. So now we're going to go ahead and use Touch index JS to create our index JS file. And inside of our index JS file, we're going to paste over the code from the API documentation. We're going to save that. And now what we're going to do is we're going to go ahead and create our private app. So now that I'm in my HubSpot account, I'm going to go to the main navigation and click on CRM Development and then click on Private Apps. Now I'm just going to go ahead and click on the Create a private app button and we'll leave the name the same. And we're going to go over to scopes, and our scopes that we're going to use are under the CRM section. We're going to do read and write. And we're also going to need to get the CRM objects contacts read information only. And this is so when we create dynamic lists, it can look for those properties that we're calling when within our list filters. Then in the top right click Create app and then in the popup click Continue creating. And finally we're going to go ahead and just click Show Token to copy it. I'm doing this in a dev account, so if you're testing things out, it's always best to do inside of a dev account. Great. So now that our private app is created, let's go back into our code. At the top, we are going to use Const HubSpot to require the API client. And then inside of here in the Const HubSpot client is where we're going to add our access token. And if you're going to do this in a real project, I would recommend putting this in a env file and then call it through that instead of putting it directly into your code. That's for just safety because then you can use Gitignore to ignore your env file and keep all of your secret tokens safe. We don't need to worry about custom properties. So we're going to just go ahead and delete out this constant here. And then here we have our const list create request. So this is what we need to send over with our API request in order for us to create a new list. So first we're going to need the object type ID. So this is going to be for context 01 for company 02 if you don't know the different object type IDs, if you're on an object page inside of your CRM and you click on the URL, you can find the object type ID within the URL. So I'm going to call Contacts. We're going to just do 01. And next we have to determine our processing type, manual, dynamic or snapshot. For this first one, we're going to do manual. This doesn't require anything else from us because we're going to add in our stuff from the front end of our HubSpot account. We don't need that custom properties anymore. So we're going to take that out. We don't have a list folder and the list folder ID is a default to 0. But if you have your lists in different folders, you can tell the API which folder you want to put it in. And then we need to give this a name. So for this one we're going to do manual API list and we don't have any filter branches right now because we're not doing a dynamic or snapshot processing type. And now inside of our Try catch, because we're using an await, I'm actually going to wrap all of this inside of a function. So we're going to create a new function and that's going to be an async function. So we're going to do async function. I'm going to just call this Create list and then we'll just write in our try catch and then as always, when you write a function, you got to call the function. So we're going to just call the function right underneath it and then we should be good to go. So now inside of our terminal we're just going to run node index JS and this will go ahead and run our code. And if it's correct, what you'll see is this output that will show that the list was created. Let's go into our HubSpot account now to see where our lists live. In the main navigation, we're going to click on CRM and then click on lists, and this will show you all the lists that you have. And so now we can see our manual API list. And as I said, a manual API list is a static type and the objects that you can add to it are contacts. And to add contacts to this, you're going to go ahead and in the main navigation, click on CRM and then contacts. And so now within our contacts we can just select some different contacts that we have. We can click on more and click on add to static list. We'll search the different static lists we have and then we go ahead and click add. You can also do this via the API. So now that we've built a static list, let's go ahead and build an active list with the processing type of dynamic. A dynamic processing type will need a filter branch, and if you choose the processing type snapshot, you will also need a filter branch. A snapshot will only run that filter branch once, and then you'll manually add stuff inside of it later. Whereas a dynamic one will always be an active list. So let's go ahead and just say filter branch because we're going to create a constant. We have to create our constant above the list create request constant. So we're going to call filter branch and then this is going to be set to an empty object right now. And then the first thing we're going to do is filter branch type. And for this one it's going to be or with the or operator it has to meet either of the group ones, but the end operator has to meet both of them. And then for this one, we're not going to add any filters to our top one. So we're just going to set this to an empty array and then we're going to add our filter branches, which is going to be an array of objects. So the first object is going to have you got to say the filter branch type. And if you see this Completion thing. It's because I'm using the node client, which is really handy. And then we're going to have our filters, which is going to be an array. And inside of our array we're going to create another object. And this is going to have our filter type. So here you're going to say what it is. Either a property, it could be an association, anything like that. We're going to use property for this one. And then next we have to say what property we want to include. So this is going to be first name and then next we're going to do the operation. So the operation is going to be an object and then inside of our operation we're going to say the operation type. This is going to be a multi string. Then we're going to set our operator to be is equal to. You can also do is not equal to lots of different operators. Let's make sure we spell operator correctly. Operator. And lastly we need to tell it what values we want it to look for. So this will be an array as well. And we're just going to look for John. We're going to go ahead and add the filter branches because you can keep nesting these inside of each other. For this one, we are not going to nest anything inside of this. So this is just going to be set to an empty array and then we're going to add another group inside of a new object. And to make this a little bit easier, we're just going to go ahead and copy the one that we just created because we're going to use the same filter branch type and filter type, but we're going to set the property to be the last name instead of first name. And then our operator is going to be is not equal to and that will be Smith. So basically what this filter branch is going to do is it's going to add contacts if their first name is John or if their last name isn't Smith. And now what we're going to do is we're going to change the name from manual to dynamic and then we're going to save that. Then now we're going to run node index JS and it built our list. So let's go into our houseweb account to see that list. So in the main navigation, click on CRM and then lists. And then we see our dynamic list. The type is active, the objects that are associated with it are contacts. And if we click on the name dynamic API list, we'll now see all of our contacts. And so here you see the filters, you can see the different groups that we created. You can see the branch operator is or if you click on Edit Filters you can go ahead and add more filter groups and it will always use the or operator as a top level filter branch and that's all you have to do. To use the new List API, check out the Resources section to links to the documentation like and subscribe to the HubSpot Developers YouTube channel and I'll see y' all in another video. I Bye bye bye.