API Contact search custom property


Since the api for search on custom property doesnt exist i have to find a workaround. Im thinking of retrieving all contacts and then looping through each contact - extracting that property and then checking it against the search criteria

The problem im having is what API do i use to get all contacts? the current one limits to 100 results returned which doesnt help me.

Please give me some ideas


Hi @carolynebrownlee! What is your end goal when searching for a specific custom property? If you are curious to see just the properties, you should be able to use this endpoint: https://developers.hubspot.com/docs/methods/contacts/v2/get_contacts_properties. If you're looking for the actual values on each contact, then the get all contacts endpoint is your best bet. You'll need to paginate through all of your contacts 100 at a time by using the has-more and vid-offset properties returned back to you.

I created a program that I pushed to Github that loops through contacts. Take a look here for an example! https://github.com/cbarley10/hubspot-pagination


Thanks so much for your response. I will accomodate this work around.
However it would really be helpful if we could do custom searches such as "&CustomPropertyName=TESTValue"


Can you help me with the URL - i only want to return a specific property for all contacts

Is this correct?


im asking because its not working

even when i add the &vidOffset={value returned in previous call where has_more was true) doesnt appear to be working either because the vidOffset returned is the same with has_more = true.

Very confusing the options available on this API

per example API documentation


doesnt return only that propery

then the response says ....has-more":true,"vid-offset":9153424}

so then i resend the url with an offset but it returns the same vid offset?



Hi @carolynebrownlee, Agreed this endpoint is a bit complex. The endpoint returns a few fields by default (lastmodifieddate firstname and lastname). When you specify a property in the URL, you will get back that field on a contact if that contact has a value for that field.

Here's an example URL: api.hubapi.com/contacts/v1/lists/all/contacts/all?hapikey=XXXXXXXXX&property=lifecyclestage&propertyMode=value_only

For your other question

When I go to this URL I can see the offset in the url is different from the offset in the response.

In the url we have 9153424 and in the response we have 9153924


OK thanks Connor it is working now :smiley:


ok next problem - this isnt going to work. To do multiple requests going through each page is not fast enough. We having multiple queries a day and its not going to work in having users wait for a response. it takes 5 minutes to go through 64 pages

Are you sure there isnt another way? is there no way this development requirement could be bumped up the dev queue?


Hi @carolynebrownlee, do you have an example of the code you've written that paginates through your contacts? My code on github I shared earlier will paginate through about 300 contacts in batches of 10 in about 5 seconds. If I bump up the limit to 100 per request, it gets returned back to me in under 2 seconds. 5 minutes seems incredibly long. How many properties are you requesting, and how many contacts are you paginating through? You should be able to get up to 100 at a time

Pagination is a pretty common design pattern for APIs such as the contacts api and we do not have plans to alter it at the moment.


Thanks Connor - we managed to narrow it down to the actual server where the request was being submitted from.
All is now sorted