list object


list object

I am creating lists thru the api,  I am updating my system on the backend so that different lists will be for different things on our website.


The create list function does not return any list id or link details.  so i have to create a get lists method.  this works out fine, until i get to having more than 50 lists. Is there a way to call all the lists back at once ?



if this is not possible how would i call a second  -> and third set of lists.  I am going to have around 500+ lists being added. 


also. the get list details  will not let you search by the list name i had just created.


I believe you are using the PHP library which is currently not returning a List object after a list is created.  This is in the process of being updated so that, in the future, the full information on a created list is returned as a list object when the createList() function is executed.  The ID is being returned, it is just not currently exposed through our sample code (you could go into the createList() function and change what is returned to return the ID if you feel comfortable).


If you are pulling down all of the existing lists, current pagination is hard coded to 50 per request.  If there are more than 50 lists, you will have a <link> node at the top level of the XML returned that will tell you the link for the next 50 lists.  This link would look something like this:


<link href="lists?next=6" rel="next" />


The getListDetails() function accepts an ID value for a list ({Username}/lists/{List_ID}) and returns the full details on that list, such as name, short name and sort order.  This is not intended to provide you any information based on the name of the list and that should cause that function to throw an error.  We currently have no options for pulling list information by a query, such as by list name, though this is something we are looking at as a possible enhancement in the future.


Hope this helps!

Dave Berard
Senior Product Manager, Constant Contact
Regular Participant

Hi Dave-


Is the concept of searching lists by name coming soon (if it's not already available)?  it just seems so heavy to have to pull down the xml for all your lists (possibly 1000s) if you're just searching for one.



I will follow-up with Dave and he or I will update this topic in response on your question about whether searching for lists by name is forthcoming to Dave, but the current version of the PHP Library should return a list object when a new list is successfully created using the addList function, and this object should include the ID and name for the list that was created, so you could store the name and associated ID locally. Having done that, it would be possible to query your own database to get the list details needed to make calls on a specific list.



Mark Coleman
Support Engineer
Regular Participant

Thanks Mark, a follow up will be greatly appreciated.  I'm not actually using the PHP library (or any library for that matter), and definitely would like to know if/when I can call something via the API to allow me to search.


I was thinking about storing some info locally, but to me that's kind of a wonky solution... where as you guys providing a proper search method would be more apt. :)


Thanks again, and hope to get an update soon.

Thanks for the question Matt.  At this time, we've announced publicly we're working on version 2 of our API.  This will include many ease of use improvements and new features, as well as moving from XML to JSON as our data format.  We don't currently have "search lists by name" on the roadmap.


Is there any chance you can put what you're looking for into a little more context of your integration?  Currently, list name is editable in all our customers accounts and isn't something you can count on being the same or even existing.  I'd like to understand more the scenario you're encountering where it would be easier to search by a name (would you want partial or exact search or both?) versus pulling all the lists (we're increasing the responses to be well past 50 per request in version 2). 

Dave Berard
Senior Product Manager, Constant Contact
Regular Participant

Thanks Dave.  Have you publicly announced when to expect v2 of the API?  JSON is a great decision by you guys.


As for my integration, here's what I'm looking to do (and absolutely feel free to poke holes in it if you want):


My site will consist of groups of people, and each group will get their own list and the name is specifically formatted by me.  The list can only be emailed to by the group leader, through my site's tools.  The CTCT integration is all behind the scenes, and only I have knowledge about list names, as it's not necessary for front-end users.


The use case I'm trying to solve is when people need to be added to a group (i.e. "Group1").  When the group leader adds a new person, the site needs to add the new person to the Group1 list.  As far as I know, the only way to get a list is by ID, which I'm not planning on storing in my database.  So, I would like to search for the list ("/lists?name=Group1"), get the ID, and add the contact to the list via the ContactList xml element.


Hopefully this all makes sense, and like I said, feel free to offer up better ways to do this.



Makes sense.  You're correct in your assumption that as of today (and in our current V2 plans), the way to reference an existing list is by the ID value.  Storing them locally would be the only way to have that reference available immediately without pulling all the lists and filtering.


I'll definitely put into our backlog the idea of searching by list name.  It sounds like in your scenario, it would be exact search that you'd want.  I don't see any reason why we'd want to limit that though to only exact search instead of partial.  Definitely something we can look at.  No promises on timing, but I see this as a definite extension of our list API that we should expose at some point in the future.


We have not publicly announced when we are releasing version 2, though we have announced to our developer community that a (very) early access beta is under.  If you're interested in taking a look at it, feel free to email us at and we can get you access to what we've exposed so far.  I'm very interested in as much early feedback from our developer community as we can possibly get.

Dave Berard
Senior Product Manager, Constant Contact
Regular Participant

Thanks Dave, appreciate the response.  Yeah, I'd definitely be doing an exact search based on list name, but I agree that it would be in your best interest to not limit it to only exact.


I do want to make sure I have one thing clear though:  If I do a GET for my lists, do you cap the number returned?  More specifically, is it possible for me to pull down 1000 lists at once?


And thanks for the heads up about the beta list.  I'll drop an email to that now, as I'm very interested in seeing what type of functionality is going to be available.



Yes, there is a limit on the number of lists returned.  We return 50, and then provide a next link to the next 50 lists in the account.  



Best Regards,

Shannon W.

API Support Specialist

Developer Portal

View API documentation, code samples, get your API key.

Visit Page