Search
Filter, sort, and search CRM objects
The CRM search endpoints make getting data more efficient by allowing developers to filter, sort, and search across any CRM object type, including contacts, deals, companies, and tickets. The contacts
scope is required to use these endpoints from an app.
Example use cases:
- Get a list of contacts for a specific HubSpot account
- Get a list of all open deals
- Search for objects (like contacts or companies) by custom properties
Supported object types and properties
These endpoints provide access to the CRM objects in the table below and return a map of property names to values. Each object type has its own set of default properties, which can be found using the CRM object properties endpoints. You can change which properties are returned in the response by using the properties
array in the request body.
Object type |
Properties returned by default |
---|---|
companies |
|
contacts |
|
deals |
|
products |
|
tickets |
|
line_items |
|
quotes |
|
custom objects |
|
Unsupported properties
engagements
, including tasks
, calls
, emails
, and notes
aren't supported.
Filters
Use filters in the request body to limit the results to only CRM objects with matching property values.
Example: Find all contacts with a first name of “Alice”
curl https://api.hubapi.com/crm/v3/objects/contacts/search?hapikey=YOUR_HUBSPOT_API_KEY \
--request POST \
--header "Content-Type: application/json" \
--data '{
"filterGroups":[
{
"filters":[
{
"propertyName": "firstname",
"operator": "EQ",
"value": "Alice"
}
]
}
]
}'
When multiple filters
are provided within a filterGroup
, they will be combined using a logical AND
operator. When multiple filterGroup
s are provided, they will be combined using a logical OR
operator. The system supports a maximum of three filterGroups
with up to three filters
each.
Example: Find all contacts with (a first name of "Alice" AND
a last name that is not "Smith") OR
has the property "enum1
"
curl https://api.hubapi.com/crm/v3/objects/contacts/search?hapikey=YOUR_HUBSPOT_API_KEY \
--request POST \
--header "Content-Type: application/json" \
--data '{
"filterGroups":[
{
"filters": [
{
"propertyName": "firstname",
"operator": "EQ",
"value": "Alice"
},
{
"propertyName": "lastname",
"operator": "NEQ",
"value": "Smith"
}
]
},
{
"filters": [
{
"propertyName": "enum1",
"operator": "HAS_PROPERTY"
}
]
}
]
}'
Operators
Supported operators:
Operator |
Description |
---|---|
|
equal to |
|
not equal to |
|
less than |
|
less than or equal to |
|
greater than |
|
greater than or equal to |
|
has property value |
|
does not have property value |
|
contains token |
|
does not contain token |
Associations
Find associations for deals
and tickets
using the associations.{objectType}
pseudo-property.
Supported association filters:
Object type |
Filter propertyName |
---|---|
deals |
|
tickets |
|
Example: Find all tickets associated with the contact with ID “123”
curl https://api.hubapi.com/crm/v3/objects/tickets/search?hapikey=YOUR_HUBSPOT_API_KEY \
--request POST \
--header "Content-Type: application/json" \
--data '{
"filters": [
{
"propertyName": "associations.contact",
"operator": "EQ",
"value": "123"
}
]
}'
curl https://api.hubapi.com/crm/v3/objects/contacts/search?hapikey=YOUR_HUBSPOT_API_KEY \
--request POST \
--header "Content-Type: application/json" \
--data '{
"sorts": [
{
"propertyName": "createdate",
"direction": "DESCENDING"
}
]
}'
Search
Perform a text search against all property values for an object type. By default, the results will be returned in order of object creation (oldest first), but you can override this with sorting.
Example: Find all contacts with a property value containing the letter x
curl https://api.hubapi.com/crm/v3/objects/contacts/search?hapikey=YOUR_HUBSPOT_API_KEY \
--request POST \
--header "Content-Type: application/json" \
--data '{
"query": "x"
}'
Default searchable properties for CRM Objects:
Object |
Default searchable properties |
---|---|
CONTACTS |
|
COMPANIES |
|
DEALS |
|
TICKETS |
|
QUOTES |
|
LINE_ITEMS |
NA |
PRODUCTS |
|
Controlling returned properties
Each object type returns a default set of properties in its search results. You can override this by providing an array of specific property names in the properties
parameter of your request body.
Example: Return all contacts and include their email and their mailing address' state
curl https://api.hubapi.com/crm/v3/objects/contacts/search?hapikey=YOUR_HUBSPOT_API_KEY \
--request POST \
--header "Content-Type: application/json" \
--data '{
"properties": [ "email", "state" ]
}'
Paging through results
By default, the search endpoints will return pages of 10 objects at a time. This can be changed by setting the limit
parameter in your request body. The maximum number of supported objects per page is 100.
Example: Get pages with size of 20
curl https://api.hubapi.com/crm/v3/objects/contacts/search?hapikey=YOUR_HUBSPOT_API_KEY \
--request POST \
--header "Content-Type: application/json" \
--data '{
"limit": 20
}
To access the next page of results, you must pass the after
parameter provided in the paging.next.after
property of the previous response. If the paging.next.after
property isn’t provided, there are no additional results to display. Note: The after
parameter is expected to be a string.
Example: Get the next page of results
curl https://api.hubapi.com/crm/v3/objects/contacts/search?hapikey=YOUR_HUBSPOT_API_KEY \
--request POST \
--header "Content-Type: application/json" \
--data '{
"after": "20"
}'
Sample success response
// Sample response
{
"results": [
{
"id": "174",
"properties": {
"firstname": "Brantley",
"lastname": "Forrest",
"email": "bforrest8@acme.com"
},
"createdAt": "2019-10-30T03:30:17.883Z",
"updatedAt": "2019-10-30T16:50:06.678Z",
"archived": false
}
],
"paging": {
"next": {
"after": "10"
}
}
}
Limitations
- It may take a few moments for newly created or updated CRM objects to show up in search results.
- Archived CRM objects won’t appear in any search results.
- These search endpoints are rate limited to four requests per second per authentication token, which is more restrictive than our general rate limits. The
X-HubSpot-RateLimit-*
headers won’t reflect this during the beta period. - The search endpoints are limited to 10,000 total results for any given query. Attempting to page beyond 10,000 will generate a 400 error.
Error handling
Learn more in our error documentation.