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.

To use these endpoints from an app, a CRM scope is required. Refer to this list of available scopes to learn which granular CRM scopes can be used to accomplish your goal.

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. In the request body, you'll include filters to narrow your search by CRM property values.

For example, the code snippet below would retrieve a list of all contacts that have a specific company email address.

Each object that you search will include a set of default properties that gets returned. For example, a contacts search will return createdate, email, firstname, hs_object_id, lastmodifieddate, and lastname. To return a specific set of properties, include a properties array in the request body. 

The tables below contain the object search endpoints, the objects they refer to, and the properties that are returned by default.

Core CRM objects

Commerce objects

The table below contains the engagement search endpoints, the engagements they refer to, and the properties that are returned by default.

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.

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

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.

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

• To apply AND logic, include a comma separated list of conditions within one set of filters.
• To apply OR logic, include multiple filters within a filterGroup.

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

For example, the request below searches for contacts with the first name Alice AND a last name other than Smith, OR contacts that don't have a value for the property email. 

You can use operators in filters to specify which records should be returned. Values in filters are case-insensitive, with the following two exceptions:

• When filtering for an enumeration property, search is case-sensitive for all filter operators.
• When filtering for a string property using IN and NOT_IN operators, the searched values must be lowercase.

Below are the available filter operators:

For example, you can use the BETWEEN operator to search for all tasks that were last modified within a specific time range:

For another example, you can use the IN operator to search for companies that have specified values selected in a dropdown property.

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: