HubSpot · Schema
HubSpot CRM Search Request
Schema for a CRM search request body used with POST /crm/v3/objects/{objectType}/search. Supports complex filtering, sorting, and pagination of CRM object records.
AnalyticsCommerceContentCRMCustomer ServiceEmail MarketingMarketingMarketing AutomationOperationsSales
Properties
| Name | Type | Description |
|---|---|---|
| filterGroups | array | An array of filter groups. Records matching ANY filter group will be included in the results (OR logic between groups). Within each filter group, ALL filters must match (AND logic within a group). Max |
| sorts | array | An array of sort criteria to order the results. When multiple sort criteria are specified, they are applied in order. |
| query | string | A full-text search query string. When provided, returns records where any searchable default text property contains the query term. Can be combined with filterGroups for more specific searches. |
| properties | array | An array of property names to include in the response for each matching record. If not specified, a default set of properties is returned. Use this to request additional properties beyond the defaults |
| limit | integer | The maximum number of results to return in a single response. Defaults to 10 if not specified. Maximum value is 200. |
| after | string | The pagination cursor token from the previous response's paging.next.after field. Used to retrieve the next page of search results. |
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://developers.hubspot.com/docs/api/schemas/crm-search-request",
"title": "HubSpot CRM Search Request",
"description": "Schema for a CRM search request body used with POST /crm/v3/objects/{objectType}/search. Supports complex filtering, sorting, and pagination of CRM object records.",
"type": "object",
"properties": {
"filterGroups": {
"type": "array",
"description": "An array of filter groups. Records matching ANY filter group will be included in the results (OR logic between groups). Within each filter group, ALL filters must match (AND logic within a group). Maximum 3 filter groups with up to 3 filters each.",
"items": {
"$ref": "#/$defs/FilterGroup"
},
"maxItems": 3,
"examples": [
[
{
"filters": [
{
"propertyName": "email",
"operator": "CONTAINS_TOKEN",
"value": "@example.com"
},
{
"propertyName": "hs_lead_status",
"operator": "EQ",
"value": "NEW"
}
]
}
]
]
},
"sorts": {
"type": "array",
"description": "An array of sort criteria to order the results. When multiple sort criteria are specified, they are applied in order.",
"items": {
"$ref": "#/$defs/Sort"
},
"maxItems": 1,
"examples": [
[
{
"propertyName": "createdate",
"direction": "DESCENDING"
}
]
]
},
"query": {
"type": "string",
"description": "A full-text search query string. When provided, returns records where any searchable default text property contains the query term. Can be combined with filterGroups for more specific searches.",
"examples": ["John Smith", "acme", "deal123"]
},
"properties": {
"type": "array",
"description": "An array of property names to include in the response for each matching record. If not specified, a default set of properties is returned. Use this to request additional properties beyond the defaults.",
"items": {
"type": "string",
"description": "A CRM property name to include in the response."
},
"examples": [
["firstname", "lastname", "email", "phone", "company"]
]
},
"limit": {
"type": "integer",
"description": "The maximum number of results to return in a single response. Defaults to 10 if not specified. Maximum value is 200.",
"default": 10,
"minimum": 1,
"maximum": 200,
"examples": [10, 50, 100, 200]
},
"after": {
"type": "string",
"description": "The pagination cursor token from the previous response's paging.next.after field. Used to retrieve the next page of search results.",
"examples": ["100"]
}
},
"$defs": {
"FilterGroup": {
"type": "object",
"description": "A group of filter conditions. All filters within the group must match (AND logic). Filter groups themselves are combined with OR logic.",
"required": ["filters"],
"properties": {
"filters": {
"type": "array",
"description": "An array of filter conditions, all of which must match (AND logic).",
"items": {
"$ref": "#/$defs/Filter"
},
"minItems": 1,
"maxItems": 3
}
}
},
"Filter": {
"type": "object",
"description": "A single filter condition for a CRM property.",
"required": ["propertyName", "operator"],
"properties": {
"propertyName": {
"type": "string",
"description": "The internal name of the CRM property to filter on.",
"examples": ["email", "firstname", "dealstage", "amount", "createdate"]
},
"operator": {
"type": "string",
"description": "The comparison operator to use for the filter.",
"enum": [
"EQ",
"NEQ",
"LT",
"LTE",
"GT",
"GTE",
"BETWEEN",
"IN",
"NOT_IN",
"HAS_PROPERTY",
"NOT_HAS_PROPERTY",
"CONTAINS_TOKEN",
"NOT_CONTAINS_TOKEN"
],
"enumDescriptions": {
"EQ": "Equal to - property value exactly matches the specified value.",
"NEQ": "Not equal to - property value does not match the specified value.",
"LT": "Less than - property value is less than the specified value (numeric/date).",
"LTE": "Less than or equal to - property value is less than or equal to the specified value.",
"GT": "Greater than - property value is greater than the specified value (numeric/date).",
"GTE": "Greater than or equal to - property value is greater than or equal to the specified value.",
"BETWEEN": "Between - property value is between value and highValue (inclusive).",
"IN": "In - property value is one of the values in the values array.",
"NOT_IN": "Not in - property value is not in the values array.",
"HAS_PROPERTY": "Has property - the property has any non-null value. No value needed.",
"NOT_HAS_PROPERTY": "Not has property - the property is null or empty. No value needed.",
"CONTAINS_TOKEN": "Contains token - text property contains the specified token (supports wildcard *).",
"NOT_CONTAINS_TOKEN": "Not contains token - text property does not contain the specified token."
}
},
"value": {
"type": "string",
"description": "The value to compare against. Not required for HAS_PROPERTY and NOT_HAS_PROPERTY operators. For date properties, use Unix timestamp in milliseconds as a string.",
"examples": ["[email protected]", "NEW", "10000", "1611608400000"]
},
"highValue": {
"type": "string",
"description": "The upper bound value for BETWEEN operator comparisons. Required when using the BETWEEN operator.",
"examples": ["50000", "1643144400000"]
},
"values": {
"type": "array",
"description": "An array of values for IN and NOT_IN operator comparisons. Use this instead of value when using IN or NOT_IN operators.",
"items": {
"type": "string"
},
"examples": [
["contractsent", "closedwon", "closedlost"],
["HIGH", "MEDIUM"]
]
}
},
"examples": [
{
"propertyName": "email",
"operator": "EQ",
"value": "[email protected]"
},
{
"propertyName": "amount",
"operator": "GTE",
"value": "10000"
},
{
"propertyName": "dealstage",
"operator": "IN",
"values": ["contractsent", "closedwon"]
},
{
"propertyName": "closedate",
"operator": "BETWEEN",
"value": "1609459200000",
"highValue": "1640995200000"
},
{
"propertyName": "email",
"operator": "HAS_PROPERTY"
}
]
},
"Sort": {
"type": "object",
"description": "A sort criterion for ordering search results.",
"required": ["propertyName"],
"properties": {
"propertyName": {
"type": "string",
"description": "The name of the CRM property to sort results by.",
"examples": ["createdate", "amount", "lastname", "dealname"]
},
"direction": {
"type": "string",
"description": "The direction to sort results. ASCENDING sorts from smallest/earliest to largest/latest. DESCENDING sorts from largest/latest to smallest/earliest.",
"enum": ["ASCENDING", "DESCENDING"],
"default": "ASCENDING"
}
},
"examples": [
{
"propertyName": "createdate",
"direction": "DESCENDING"
},
{
"propertyName": "amount",
"direction": "DESCENDING"
}
]
}
},
"examples": [
{
"filterGroups": [
{
"filters": [
{
"propertyName": "email",
"operator": "CONTAINS_TOKEN",
"value": "@example.com"
}
]
}
],
"properties": ["email", "firstname", "lastname", "phone"],
"limit": 20,
"sorts": [
{
"propertyName": "createdate",
"direction": "DESCENDING"
}
]
},
{
"filterGroups": [
{
"filters": [
{
"propertyName": "dealstage",
"operator": "EQ",
"value": "contractsent"
},
{
"propertyName": "amount",
"operator": "GT",
"value": "10000"
}
]
},
{
"filters": [
{
"propertyName": "dealstage",
"operator": "EQ",
"value": "closedwon"
}
]
}
],
"sorts": [
{
"propertyName": "amount",
"direction": "DESCENDING"
}
],
"properties": ["dealname", "amount", "dealstage", "closedate", "hubspot_owner_id"],
"limit": 50
}
]
}