Master HubSpot API Search: Your Ultimate Guide to Finding CRM Data

Ever felt like you’re digging through a haystack when you need a specific piece of customer data in HubSpot? Don’t worry, you’re not alone. Manually sifting through records can be a real time-sink, especially when you’re dealing with hundreds or thousands of contacts, companies, or deals. But what if you could snap your fingers and pull exactly what you need, programmatically? That’s where the HubSpot API search comes in – it’s your personal superpower for quickly and efficiently finding CRM data.

To really get a handle on HubSpot API search, you should think of it as your direct line to HubSpot’s CRM database, allowing you to ask precise questions and get back exactly the information you want, without clicking through countless pages. It’s an absolute game-changer for automating tasks, keeping your systems synced, and building custom applications that truly leverage your HubSpot data.

In this guide, we’re going to break down everything you need to know about searching HubSpot’s CRM via its API. We’ll start with the basics, like how to authenticate and structure your requests, and then move into more advanced techniques. We’ll explore how to search for different types of CRM objects, like contacts, companies, and deals, and even your custom objects. Plus, we’ll cover some crucial tips on handling common challenges like rate limits and tricky data formats. By the end of this, you’ll be a pro at fetching data from HubSpot, making your workflows smoother and your integrations smarter.

Getting Started: The Essentials of HubSpot API Search

Before we jump into specific search queries, let’s lay down the groundwork. Think of these as your basic tools and rules for interacting with the HubSpot API.

0.0 0.0 out of 5 stars (based on 0 reviews) Excellent0% Very good0% Average0% Poor0% Terrible0% There are no reviews yet. Be the first one to write one. Your review Your overall rating Select a Rating5 Stars4 Stars3 Stars2 Stars1 Star Title of your review Your review Your name Your email This review is based on my own experience and is my genuine opinion. ​ Submit Review

Amazon.com: Check Amazon for Master HubSpot API Latest Discussions & Reviews:

Authentication: Your Key to the Kingdom

First things first, you need to tell HubSpot who you are and that you’re allowed to access its data. This is called authentication. For most internal tools or applications you build for your own HubSpot account, using Private App Tokens is generally the easiest and most secure method.

You can set these up in your HubSpot account settings under ‘Integrations’ > ‘Private Apps’. When creating a private app, you’ll choose specific “scopes” – these are permissions that define what your app can do. For searching CRM objects, you’ll usually need crm.objects.contacts.read, crm.objects.companies.read, crm.objects.deals.read, and crm.objects.custom_objects.read, depending on what data you plan to access. It’s good practice to only grant the minimum necessary permissions. Once you create the app, you’ll get a unique access token. Guard this token carefully – it’s like a password for your data!

The Search Endpoint: Your Go-To Tool

When you want to search for something in HubSpot’s CRM, you’re primarily going to use a specific type of API request: a POST request to the /crm/v3/objects/{objectType}/search endpoint.

Let’s break that down: Why Blend HubSpot Data with Power BI?

• POST Request: Instead of a GET request which usually just fetches data without a complex body, a POST request here allows you to send a detailed JSON “body” with your search criteria.
• /crm/v3/objects/{objectType}/search: This is the base URL for most of your CRM searches.
  • v3: This indicates you’re using version 3 of the CRM API, which is the current standard. Though, keep an eye out, as HubSpot is rolling out date-based versioning!
  • {objectType}: This is where you specify what you’re searching for. Common values include:
    • contacts
    • companies
    • deals
    • The fullyQualifiedName or objectTypeId for your custom_objects.

So, if you want to search your contacts, your endpoint would look something like https://api.hubapi.com/crm/v3/objects/contacts/search.

Making Sense of Your Data: Basic Search Queries

Now that you know how to get in the door, let’s talk about actually finding things. The core of a HubSpot API search request is its JSON body, where you define your filters and specify what properties you want back.

Simple Property Filtering

The most common way to search is by filtering records based on their property values. You do this using filterGroups and filters in your request body.

Here’s a basic structure: App hubspot com login legacy

{
  "filterGroups": 
    {
      "filters": 
        {
          "propertyName": "email",
          "operator": "EQ",
          "value": "[email protected]"
        }
      
    }
  
}

Let’s unpack this:

• filterGroups: This is an array that can hold one or more groups of filters. You can think of each group as an “AND” condition, and filters within a group as “OR” conditions though you can achieve “AND” within a group as well, by listing multiple filters.
• filters: An array of individual filter objects.
• propertyName: This is the internal name of the HubSpot property you want to filter by e.g., email, firstname, hs_object_id. You can find these internal names in your HubSpot account settings under ‘Properties’.
• operator: This defines how the propertyName should be compared to the value. Some common operators include:
  • EQ: Equal to
  • NEQ: Not equal to
  • GT: Greater than
  • LT: Less than
  • BETWEEN: Within a range
  • IN: Is one of a list of values
  • NOT_IN: Is not one of a list of values
  • CONTAINS_TOKEN: Useful for partial matches, especially with email domains or names. If you wanted to find contacts with any email from “domainname.com”, you’d use CONTAINS_TOKEN with a value of *@domainname.com.
• value: The specific value you’re looking for.

Example: hubspot api search contact by email

One of the most frequent searches is finding a contact by their email address. It’s super straightforward:

       "value": "[email protected]"

This request sends a query to the HubSpot API to find a contact where the ’email’ property is exactly ‘[email protected]‘. It’s a precise way to locate individual contacts when you have their email.

Retrieving Specific Information properties

By default, when you search, HubSpot will return a few standard properties like createdate, email, firstname, hs_object_id, lastmodifieddate, and lastname for contacts. But let’s be real, you usually need more than just the defaults! Supercharge Your HubSpot: A Real Look at App Cards

To get specific properties, you add a properties array to your request body:

,
“properties”:
Adding properties to your request ensures that you only get the data you actually need, which can help keep your API responses lean and efficient.

Beyond the Basics: Advanced Search Techniques

Once you’re comfortable with basic filtering, you’ll quickly realize the HubSpot API offers a lot more power. Let’s dig into searching different CRM objects and handling more complex scenarios.

Searching Specific CRM Objects

The beauty of the CRM search endpoint is its versatility across all your core HubSpot objects. Is VPN Safe for Ayman? Unpacking Online Security

Contacts

When you’re dealing with hubspot api search contacts, there are a couple of common scenarios you’ll encounter beyond just email.

• By Email hubspot api search contact by email: As we saw, this is typically done using the email property and the EQ operator. It’s often the most reliable unique identifier.

• By Phone Number hubspot api search contact by phone number: This one can be a bit trickier, but it’s definitely possible. You’ll use properties like phone or mobilephone. The catch? HubSpot can be particular about phone number formatting. Often, it strips non-numeric characters when storing numbers, so ” 555 123-4567″ becomes “5551234567” internally.

  Pro Tip for Phone Numbers: It’s best practice to normalize your phone numbers by removing all non-numeric characters before sending them in your search query. Also, HubSpot uses special calculated properties, like hs_searchable_calculated_*, to standardize phone numbers, typically focusing on the area code and local number. You should generally avoid including the country code in your search criteria if you’re not getting results.

  Here’s an example for searching contacts by phone number: Is Using a VPN Legal in the Cayman Islands?

    "filterGroups": 
        "filters": 
          {
            "propertyName": "phone",
            "operator": "EQ",
            "value": "5551234567"
          }
        
    ,
    "properties": 
  

  You might even need to try searching both phone and mobilephone properties if you’re not sure where the number is stored.

Companies

Need to find specific businesses in your CRM? The hubspot api search company by name or by other properties is a common task.

       "propertyName": "name",
       "operator": "CONTAINS_TOKEN",
       "value": "Acme Corp"

“properties”:
This search allows you to find companies with “Acme Corp” anywhere in their name. You could also filter by domain using EQ for an exact match.

Deals

The hubspot api search deals endpoint is super useful for sales teams looking to track progress or identify specific opportunities. You can filter by dealname, amount, closedate, dealstage, pipeline, and more.

       "propertyName": "dealstage",
       "value": "appointmentscheduled"
     },
       "propertyName": "amount",
       "operator": "GT",
       "value": 1000

“properties”:
This example finds deals in the “Appointment Scheduled” stage with an amount greater than 1000. Remember to use the internal names for deal stages and pipelines! Is VPN Safe for Azure VM? Your Ultimate Guide to Secure Connections

Custom Objects

If your business has unique data structures in HubSpot, you’re probably using custom objects. The good news is the search API works for them too!

• hubspot api search custom object: To search a custom object, you’ll need its objectTypeId or fullyQualifiedName. You can find these in your HubSpot account settings or via the Custom Objects API.

• Searchable Properties: Just like standard objects, you’ll use propertyName in your filters. However, for custom objects, you need to ensure those properties are actually marked as “searchable” in the custom object’s schema definition.

     "propertyName": "car_make",
     "value": "Toyota"
  

“properties”:
Here, car_make would be a custom property on your “Car” custom object.

Working with Associations

Sometimes, you don’t just want to find an object. you want to find objects based on their relationships with other objects. This is where hubspot api search associations comes in. Is VPN Safe for Azure Firewall? Let’s Break It Down

For example, you might want to find all contacts associated with a specific company. While the search API is powerful, filtering directly on complex associations within the main search endpoint can sometimes be less intuitive than one might hope.

According to some community discussions, you might need to use “pseudo-property associations” or consider alternative methods for very complex association filtering. The v4 Associations API offers more advanced ways to manage these relationships.

A common approach if direct association filtering in the search API feels too complex is:

1. Find the primary object e.g., a company using the search API.
2. Then, use the Associations API to retrieve all associated objects e.g., contacts related to that company using the ID of the primary object you just found.

For instance, to get all contacts associated with a company, you might first search for the company, then use a separate API call to list associations from that company to contacts.

Combining Filters filterGroups

You can create more sophisticated searches by using multiple filterGroups or multiple filters within a single group. Is VPN Automatically On iPhone? Let’s Break It Down

• AND logic between filterGroups: If you have multiple filterGroups, HubSpot treats them as an “AND” condition. All conditions in all groups must be met.
• OR logic within filters within a filterGroup: If you have multiple filters within the same filterGroup, these act as an “OR” condition. Any one of those filters being true will satisfy that filterGroup.

To achieve an “AND” condition between multiple properties in a single filter group, you simply list them:

       "propertyName": "firstname",
       "value": "John"
       "propertyName": "lastname",
       "value": "Doe"

“operator”: “AND” // This implicitly acts as AND for filters in the same group.
In this particular request, propertyName: "firstname", operator: "EQ", value: "John" and propertyName: "lastname", operator: "EQ", value: "Doe" are both within the same filter group, and because there isn’t an explicit “OR” operator, they act as an “AND” condition, meaning the API will look for contacts where both the first name is “John” and the last name is “Doe”.

If you wanted to search for contacts named “John Doe” OR “Jane Smith”, you’d use multiple filterGroups:

 },
       "value": "Jane"
       "value": "Smith"

The above request would look for contacts matching the first criteria set OR the second criteria set.

Sorting Your Results sort

Getting a list of records is great, but sometimes you need them in a specific order. You can use the sort array in your request body to order your results by property name and direction ascending or descending. Is VPN Safe for Asia? A Traveler’s Guide to Staying Secure Online

       "propertyName": "lifecyclestage",
       "value": "lead"

“properties”: ,
“sorts”:
“propertyName”: “createdate”,
“direction”: “DESCENDING”
This query would return leads, sorted by their createdate from newest to oldest.

Managing Large Datasets limit and after for Pagination

You’re probably not going to get all your contacts in one go. HubSpot’s API has some sensible limits in place to ensure performance.

• hubspot api search limit: By default, the API returns up to 10 results per page, but you can specify a limit of up to 200 records per page.

• Total Results Limit: Importantly, the search endpoints are limited to 10,000 total results for any given query. If your search would return more than 10,000 records, you’ll need to adjust your filters or paginate carefully.

• Pagination with after: To get more than 200 records or whatever your limit is, you’ll need to paginate through the results. Each response includes an after cursor in the paging object. You include this after value in your next request to get the next “page” of results. Is a VPN Safe for AQI? Understanding the Link Between Privacy, Security, and Air Quality Data

     "propertyName": "createdate",
     "value": "2024-01-01T00:00:00.000Z"
  

“properties”: ,
“limit”: 100,
“after”: “YOUR_PREVIOUS_AFTER_CURSOR_VALUE” // Only include this in subsequent requests
You’d keep making requests, updating the after value with each response’s paging.next.after value, until no more after value is returned, meaning you’ve reached the end of the results.

The query Field

You might have noticed a query field mentioned in some documentation or examples hubspot api search query. It’s different from filterGroups. The query field performs a general search across default searchable properties e.g., firstname, lastname, email for contacts. It’s less precise than filterGroups but can be useful for a broad text search. If you need exact matches or complex logic, filterGroups is your go-to.

“query”: “John Doe”,
“properties”:
This would search across default searchable properties for “John Doe”.

Common Gotchas & Best Practices

Even with all this power, there are a few things that can trip you up. Here’s what to look out for and how to make your HubSpot API searches smooth sailing. Which is the Safest VPN App?

Rate Limits: The Big One!

This is probably the most common challenge developers face. The HubSpot CRM search API endpoints are rate limited to five requests per second per account. This means if you have multiple applications or users hitting the search API at the same time, all those requests count towards that same limit. Exceeding this limit will result in 429 errors Too Many Requests.

Strategies to handle rate limits:

• Implement retries with exponential backoff: If you get a 429 error, wait a bit longer before trying again.
• Batch your requests: Where possible, group multiple operations into a single API call. While the search API is for retrieving, if you’re then acting on those results, look for batch endpoints e.g., batch update contacts to reduce your overall API calls.
• Throttle your requests: Build logic into your application to ensure you don’t send more than 5 requests per second.
• Cache data: For frequently accessed but slowly changing data, store it locally for a period instead of hitting the API every time.

Property Names: Internal is Key

Always use the internal name of a property in your API requests, not the label you see in the HubSpot UI. These can sometimes be different. You can find the internal names by looking at the property details in your HubSpot account settings.

Data Consistency: Formatting Matters

We already touched on phone numbers, but this applies to other data too. Be mindful of:

• Case sensitivity: Some properties might be case-sensitive.
• Dates: Always use ISO 8601 format e.g., YYYY-MM-DDTHH:MM:SS.sssZ for date properties.
• Dropdown/Enumeration properties: Use the internal value of the option, not its display label.

Error Handling: Expect the Unexpected

Always build robust error handling into your code. The API might return various error codes like 400 for bad request, 401 for unauthorized, 404 for not found, 429 for rate limit, 500 for server error. Your application should be able to gracefully handle these and provide informative feedback. Is Free VPN Safe on Apple Devices? (A Real Talk Guide)

Using Postman/Testing Tools

Before writing a single line of code, use a tool like Postman to test your API requests. It lets you quickly build and send requests, see the responses, and tweak your JSON body until everything is just right. This saves a ton of development time and helps you understand exactly how the API behaves.

Staying Updated: The API Evolves

HubSpot is constantly improving its APIs. They’re even moving to a date-based versioning system for some CRM APIs, which means instead of v3, you might see 2025-09 in the endpoint. Keep an eye on the HubSpot Developer Changelog and documentation developers.hubspot.com to stay informed about new features, deprecations, and changes.

Frequently Asked Questions

What’s the best way to search for a contact if I only have their email?

The best and most direct way to search for a contact by email is to use the /crm/v3/objects/contacts/search endpoint with a filterGroup targeting the email property and using the EQ equals operator. For example:
“value”: “[email protected]”
This ensures an exact match and is generally very efficient because email is a primary identifier in HubSpot.

Is vpn safe for allowed in fortnite

How do I deal with HubSpot API rate limits when searching?

HubSpot’s search API has a rate limit of 5 requests per second per account. To manage this, you should implement strategies like:

1. Throttling: Design your application to never send more than the allowed number of requests within the given time frame.
2. Exponential Backoff: If you hit a 429 error, wait for a progressively longer period before retrying the request.
3. Batching: While the search API is for single object searches, for subsequent operations on found records, use HubSpot’s batch endpoints to combine multiple updates or creations into a single API call, reducing your overall request count.
4. Caching: For data that doesn’t change frequently, store it locally in your application for a set period rather than making repetitive API calls.

Can I search custom objects with the HubSpot API?

Yes, absolutely! The HubSpot CRM search API supports searching custom objects just like standard objects contacts, companies, deals. You’ll use the same /crm/v3/objects/{objectType}/search endpoint, but for {objectType}, you’ll need to provide the custom object’s fullyQualifiedName or objectTypeId. Just make sure that the properties you intend to search by are marked as “searchable” in your custom object’s schema definition.

What’s the difference between the query field and filterGroups in a search request?

The query field and filterGroups serve different purposes in the HubSpot API search.

• The query field performs a broad, general text search across a predefined set of default searchable properties for the object type e.g., firstname, lastname, email for contacts. It’s good for a quick, less specific search.
• filterGroups, on the other hand, allows for highly specific and granular searching. You explicitly define the propertyName, operator, and value, enabling complex logic like “equal to,” “greater than,” “contains token,” and combining multiple conditions with AND/OR. This is your go-to for precise data retrieval.

Why am I not getting all the properties I expect in my search results?

By default, the HubSpot API search endpoint only returns a limited set of core properties for each object type e.g., hs_object_id, createdate, email, firstname, lastname for contacts. If you need additional properties, you must explicitly request them by including a properties array in your JSON request body. For example, to get a contact’s company and lifecyclestage in addition to the defaults, your request would include:
// … your filters …
“properties”:
If a requested property is defined but the record doesn’t have a value for it, that property might be returned as null or not included in the response.

How does HubSpot handle phone number formatting for search?

HubSpot can be particular about phone number formatting. When phone numbers are stored, HubSpot often strips out non-numeric characters like parentheses, dashes, and spaces. For searching, it also uses special internal calculated properties starting with hs_searchable_calculated_* that standardize numbers, typically focusing on the area code and local number without country codes. Is a VPN Safe for Ajay Devgan (and You!)? Unpacking Online Security

Therefore, when you search by phone number using properties like phone or mobilephone, it’s a best practice to:

1. Normalize your search input: Remove all non-numeric characters from the phone number you’re searching with.
2. Avoid country codes: Refrain from including country codes in your search criteria, as HubSpot’s internal search often ignores them.
3. Consider multiple fields: If you’re unsure where a number is stored, you might need to search across both phone and mobilephone properties.