Resources
Find Records
Filter records by any property with compound filter groups, or batch-fetch a specific set of records by their IDs in a single request.
Filter
Compound filter over any object type. filter_groups are combined with OR; the filters within one group are combined by the group's logical_operator (AND / OR). Two examples are shown below - a single-field filter (contacts in one city) and a multi-field filter (contacts by owner + city + recent activity).
Path parameters
object string · required | Object type - one of contact, company, deal, note, meeting, task. |
Request body
filter_groups array · required | One or more groups. Groups are combined with OR. Each group has logical_operator (AND/OR, defaults to AND) and a filters array. |
filters[].field_path string · required | The property name to filter on. Always snake_case (e.g. owner_id, city, last_activity_date). |
filters[].operator string · required | Comparison operator - see the table below. |
filters[].value / values any | value for single-value operators; values (array) for IN, NOT_IN, BETWEEN. Omit for IS_NULL/IS_NOT_NULL. |
pagination object | { page, page_size }. Same defaults as list endpoints (page 1, size 20, max 100). |
sort object | { field, direction }. direction is ASC or DESC. Field must be snake_case. |
Operators
| Operator | Value field | Works with |
|---|---|---|
EQUALS | value | All field types |
NOT_EQUALS | value | All field types |
GREATER_THAN | value | Numbers, dates |
LESS_THAN | value | Numbers, dates |
GREATER_THAN_OR_EQUAL_TO | value | Numbers, dates |
LESS_THAN_OR_EQUAL_TO | value | Numbers, dates |
BETWEEN | values (array of 2) | Inclusive range - numbers, dates |
IN | values (array) | Match any value in the array |
NOT_IN | values (array) | Exclude any value in the array |
IS_NULL | - | Field is empty |
IS_NOT_NULL | - | Field is not empty |
CONTAINS | value | Substring match - text fields |
STARTS_WITH | value | Prefix match - text fields |
ENDS_WITH | value | Suffix match - text fields |
Body keys accept both cases
You can send filter_groups/field_path (snake_case) or filterGroups/fieldPath (camelCase). Both are accepted. Field names inside field_path and sort.field are always snake_case - e.g. created_at, not createdAt.
Returns
The matching records, paginated the same way as List Records (results, metadata with page, page_size, total_elements, total_pages, has_next, has_previous).
curl 'https://api.dreamteamcrm.ai/api/v1/objects/contact/records/filter' \
-X POST \
-H 'Authorization: Bearer <YOUR_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
"filter_groups": [
{
"filters": [
{
"field_path": "city",
"operator": "EQUALS",
"value": "San Francisco"
}
]
}
],
"pagination": {
"page": 1,
"page_size": 25
}
}'curl 'https://api.dreamteamcrm.ai/api/v1/objects/company/records/filter' \
-X POST \
-H 'Authorization: Bearer <YOUR_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
"filter_groups": [
{
"filters": [
{
"field_path": "industry",
"operator": "EQUALS",
"value": "Hardware"
}
]
}
],
"pagination": {
"page": 1,
"page_size": 25
}
}'curl 'https://api.dreamteamcrm.ai/api/v1/objects/deal/records/filter' \
-X POST \
-H 'Authorization: Bearer <YOUR_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
"filter_groups": [
{
"filters": [
{
"field_path": "amount",
"operator": "GREATER_THAN_OR_EQUAL_TO",
"value": 50000
}
]
}
],
"pagination": {
"page": 1,
"page_size": 25
}
}'{
"results": [
{
"id": 1015634,
"properties": {
"first_name": "Ada",
"last_name": "Chen",
"email": "ada@example.com",
"owner_id": 1000052,
"city": "San Francisco",
"last_activity_date": "2026-06-14T09:22:11.104Z"
}
}
],
"metadata": {
"page": 1,
"page_size": 25,
"total_elements": 1,
"total_pages": 1,
"has_next": false,
"has_previous": false
}
}{
"results": [
{
"id": 1011597,
"properties": {
"name": "Analytical Engines Ltd",
"domain": "analytical-engines.com",
"industry": "Hardware",
"owner_id": 1000052
}
}
],
"metadata": {
"page": 1,
"page_size": 25,
"total_elements": 1,
"total_pages": 1,
"has_next": false,
"has_previous": false
}
}{
"results": [
{
"id": 1011624,
"properties": {
"name": "Analytical Engines - Q3",
"amount": 100000.0,
"stage_id": 1000003,
"pipeline_id": 1000000,
"owner_id": 1000052
}
}
],
"metadata": {
"page": 1,
"page_size": 25,
"total_elements": 1,
"total_pages": 1,
"has_next": false,
"has_previous": false
}
}Batch Fetch by IDs
When you already have a list of record IDs, hit the same Filter endpoint with an IN filter on id to get them all in a single call. This isn't a separate endpoint — it's the filter pattern you'll reach for most often.
When to use it
- Hydrating associated records. A Get Record or List Records response embeds associations as
{id, association_name}pairs. One call replaces N individual Get Record calls. - Working from a set of IDs - from a search result, a webhook payload, a spreadsheet import, or anywhere else you already have IDs on hand.
Request body
A single filter group with one IN filter on id. Pass the list of ids in values. See the Filter section above for the full body schema.
curl 'https://api.dreamteamcrm.ai/api/v1/objects/company/records/filter' \
-X POST \
-H 'Authorization: Bearer <YOUR_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
"filter_groups": [
{
"filters": [
{
"field_path": "id",
"operator": "IN",
"values": [1011597, 1011598]
}
]
}
]
}'{
"results": [
{
"id": 1011597,
"properties": {
"name": "Analytical Engines Ltd",
"domain": "analytical-engines.com",
"industry": "Hardware",
"company_size": 240
}
},
{
"id": 1011598,
"properties": {
"name": "Babbage Systems",
"domain": "babbagesystems.com",
"industry": "Technology",
"company_size": 780
}
}
],
"metadata": {
"page": 1,
"page_size": 20,
"total_elements": 2,
"total_pages": 1,
"has_next": false,
"has_previous": false
}
}