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

name, domain, createdate, hs_lastmodifieddate, hs_object_id

contacts

firstname, lastname, email, createdate, lastmodifieddate, hs_object_id

deals

dealname, amount, closedate, pipeline, dealstage, createdate, hs_lastmodifieddate, hs_object_id

products

name, description, price, createdate,  hs_lastmodifieddate, hs_object_id

tickets

content, hs_pipeline, hs_pipeline_stage, hs_ticket_category, hs_ticket_priority, subject, createdate, hs_lastmodifieddate, hs_object_id

line_items

quantity, amount, price, createdate, hs_lastmodifieddate, hs_object_id

quotes

hs_expiration_date, hs_public_url_key, hs_status, hs_title, hs_createdate, hs_lastmodifieddate, hs_object_id

custom objects

hs_createdate, hs_lastmodifieddate, hs_object_id
 

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”

Shell script 
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 filterGroups 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"

Shell script 
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

EQ

equal to

NEQ

not equal to

LT

less than

LTE

less than or equal to

GT

greater than

GTE

greater than or equal to

HAS_PROPERTY

has property value

NOT_HAS_PROPERTY

does not have property value

CONTAINS_TOKEN

contains token

NOT_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

associations.company,
associations.contact,
associations.ticket

tickets

associations.company,
associations.contact,
associations.deal

 

Example: Find all tickets associated with the contact with ID “123”

Shell script 
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"
      }
    ]
  }'

Sort

Use a sorting rule in the request body to see results in a specific order (ascending or descending). Only one sorting rule can be applied to any search.

Example: List all contacts with most recently created first.

Shell script 
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

Shell script 
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 

"firstname",

"hs_additional_emails",

"phone",

"fax",

"mobilephone"

"company",

"email",

"lastname"

COMPANIES 

"website",

"phone",

"domain",

"name"

DEALS

“pipeline",

"dealname",

"dealstage",

"dealtype",

"description"

 

TICKETS

"hs_ticket_category",

"hs_ticket_id",

"subject",

"hs_pipeline_stage",

"content"

 

QUOTES

"hs_sender_firstname",

"hs_title",

"hs_sender_company_name",

"hs_sender_email",

"hs_quote_number",

"hs_sender_lastname",

"hs_public_url_key"

 

LINE_ITEMS

NA

PRODUCTS

"price",

"name",

"description"

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

Shell script 
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

Shell script 
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

Shell script 
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

JSON 
// 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.