Search 

Use the CRM search endpoints to filter, sort, and search objects, records, and engagements across your CRM. For example, use the endpoints to get a list of contacts in your account, or a list of all open deals.

The contacts scope is required to use these endpoints from an app.

Make a search request

To search your CRM, make a POST request to the object's search endpoint. CRM search endpoints are constructed using the following format:

/crm/v3/objects/{object}/search

The table below contains the searchable CRM objects, their search endpoints, and the properties that are returned by default. Learn more about specifying returned properties.

OBJECT  SEARCH ENDPOINT DEFAULT RETURNED PROPERTIES

Companies

/crm/v3/objects/companies/search

name,
domain,
createdate,
hs_lastmodifieddate,
hs_object_id

Contacts

/crm/v3/objects/contacts/search

firstname,
lastname, 
email,
lastmodifieddate, 
hs_object_id,
createdate 

Custom objects

/crm/v3/objects/{objectType}/search

hs_createdate,
hs_lastmodifieddate,
hs_object_id

Deals

/crm/v3/objects/deals/search

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

Feedback submissions

/crm/v3/objects/feedback_submissions/search

hs_createdate,
hs_lastmodifieddate,
hs_object_id

Products

/crm/v3/objects/products/search

name,
description,
price,
createdate,
hs_lastmodifieddate,
hs_object_id

Tickets

/crm/v3/objects/tickets/search

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

Line items

/crm/v3/objects/line_items/search

quantity,
amount,
price,
createdate,
hs_lastmodifieddate,
hs_object_id

Quotes

/crm/v3/objects/quotes/search

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

The table below contains the searchable CRM engagements, their search endpoints, and the properties that are returned by default. Learn more about specifying returned properties.

Please note: the engagements API is currently in beta and is subject to change based on testing and feedback. By using these endpoints you agree to adhere to our Developer Terms& Developer Beta Terms. You also acknowledge and understand the risk associated with testing an unstable API.

 

ENGAGEMENT SEARCH ENDPOINT DEFAULT RETURNED PROPERTIES

Calls

/crm/v3/objects/calls/search

hs_createdate,
hs_lastmodifieddate,
hs_object_id

Emails

/crm/v3/objects/emails/search

hs_createdate,
hs_lastmodifieddate,
hs_object_id

Meetings

/crm/v3/objects/meetings/search

hs_createdate,
hs_lastmodifieddate,
hs_object_id

Notes

/crm/v3/objects/notes/search

hs_createdate,
hs_lastmodifieddate,
hs_object_id

Tasks

/crm/v3/objects/tasks/search

hs_createdate,
hs_lastmodifieddate,
hs_object_id

To make a basic search, returning only default properties with no additional filtering or sorting, include only an empty object in the request body. For example:

JSON 
// Example POST request to /crm/v3/objects/contacts/search

{}

Filter search results

Use filters in the request body to limit the results to only records with matching property values.

For example, the request below searches for 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"
          }
        ]
      }
    ]
  }'

To include multiple filter criteria, you can group filters within filterGroups:

  • When multiple filters are present within a filterGroup, they'll be combined using a logical AND operator.
  • When multiple filterGroups are included in the request body, they'll be combined using a logical OR operator.

You can include a maximum of three filterGroups with up to three filters in each group.

For example, the request below searches for all contacts with a first name of Alice and a last name that is not Smith, OR has a value for 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"
           }
         ]
       }
    ]
  }'

You can use the following operators in a filter:

Use this table to describe parameters / fields
OperatorDescription
LT

Less than

LTE

Less than or equal to

GT

Greater than

GTE

Greater than or equal to

EQ

Equal to

NEQ

Not equal to

HAS_PROPERTY

Has a value for the specified property.

NOT_HAS_PROPERTY

Doesn't have a value for the specified property.

CONTAINS_TOKEN

Contains a token.

NOT_CONTAINS_TOKEN

Doesn't contain a token.

Search through associations

Search for records that are associated with other specific records by using the pseudo-property associations.{objectType}.

For example, the request below searches for all tickets associated with a contact that has the contact ID of 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"
      }
    ]
  }'

You can search through associations by using the following pseudo-property values:

  • associations.company
  • associations.contact
  • associations.ticket
  • associations.deal
  • associations.quote

To search for associations to a specific custom object record, you can use use the above pseudo--property with the custom object's objectTypeId, which you can retrieve through the custom object's schema. For example, associations.2-214573.

Sort search results

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

For example, the request below sorts returned 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 default searchable properties

Search all default text properties in records of the specified object to find all records that have a value containing the specified string. By default, the results will be returned in order of object creation (oldest first), but you can override this with sorting.

For example, the request below searches for all contacts with a default text 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"
  }'

Below are the properties that are searched by default through the above method:

OBJECT/Engagement DEFAULT SEARCHABLE PROPERTIES

Calls

"hs_call_title",
"hs_body_preview"

Companies

"firstname",
"hs_additional_emails",
"phone",
"fax",
"mobilephone",
"company",
"email",
"lastname"

Contacts

"website",
"phone",
"domain",
"name"

Custom objects

“pipeline",
"dealname",
"dealstage",
"dealtype",
"description"

Deals

"hs_ticket_category",
"hs_ticket_id",
"subject",
"hs_pipeline_stage",
"content"

Emails

"hs_email_subject"

Feedback submissions

"hs_sender_firstname",
"hs_title",
"hs_sender_company_name",
"hs_sender_email",
"hs_quote_number",
"hs_sender_lastname",
"hs_public_url_key"

Meetings

"hs_meeting_body"

Notes

"hs_note_body"

Products

"price",
"name",
"description"

Tasks

"hs_task_body",
"hs_task_subject"

Tickets

"hs_content",
"hs_submission_name"

Line items

 N/A

Quotes

"hs_sender_firstname",
"hs_proposal_slug",
"hs_title",
"hs_sender_company_name",
"hs_sender_email",
"hs_quote_number",
"hs_sender_lastname",
"hs_public_url_key"

Specify returned properties

Each request will return a default set of properties in its search results for the requested object. You can override this by providing an array of specific property names in the properties parameter of your request body. 

For example, the request below searches all contacts and will return their email and 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 records at a time. This can be changed by setting the limit parameter in the request body. The maximum number of supported objects per page is 100.

For example, the request below would return pages containing 20 results each.

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 an 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. You must format the value in the after parameter as a string.

For example, the request below would return 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"
  }'

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. HubSpot will only return the X-HubSpot-RateLimit-Daily and X-HubSpot-RateLimit-Daily-Remaining headers.
  • The search endpoints are limited to 10,000 total results for any given query. Attempting to page beyond 10,000 will result in a 400 error.
  • When searching for phone numbers, HubSpot uses special calculated properties to standardize the format. These properties all start with hs_searchable_calculated_*. As a part of this standardization, HubSpot only uses the area code and local number. You should refrain from including the country code in your search or filter criteria.
Was this page helpful? *
This form is for feedback on our developer docs. If you have feedback on the HubSpot product, please share it in our Idea Forum instead.