Search
Find records of an object type by their property values, by free text, or both.
Search records
Returns every record of the object type that matches the request. With an empty body, every record is returned.
POST/objects/{objectType}/search
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| objectType | string | required | Object type id (0-1 contacts, 0-2 companies, 0-3 deals, 2-… custom objects) or its name, e.g. contacts. |
Request Body
| Name | Type | Required | Description |
|---|---|---|---|
| filterGroups | array | optional | Groups of filters. A record matches when it matches every filter of at least one group. |
| filters | array | optional | A single list of filters that must all match. Use it instead of filterGroups when you need no OR. |
| query | string | optional | Free text searched in the main properties of the object type. |
Example Request (cURL) · bash
curl --location --request POST 'https://api-proxy-v1.rubikchat.com/api/crm/v3/objects/contacts/search' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'X-Organization-Slug: your-organization-slug' \
--header 'Content-Type: application/json' \
--data '{
"filterGroups": [
{
"filters": [
{
"propertyName": "email",
"operator": "CONTAINS_TOKEN",
"value": "example.com"
}
]
}
]
}'Status: 200 OK
Example Response · json
{
"total": 1,
"results": [
{
"id": "6f1c2a9e-3b4d-4c8a-9f21-7d5e0b8a1c34",
"properties": {
"firstname": "Ali",
"lastname": "Khan",
"email": "[email protected]",
"phone": "+923001234567"
},
"createdAt": "2026-11-12T10:00:00.000Z",
"updatedAt": "2026-11-12T10:00:00.000Z",
"archived": false
}
]
}Filters and filter groups
A filter compares one property of the record with a value:
Filter
| Field | Type | Description |
|---|---|---|
| propertyName | string | The internal name of the property, e.g. email. |
| operator | string | One of the operators below. Defaults to EQ. |
| value | string | array | The value to compare with. An array for IN and IN_OR_EMPTY. |
- Filters inside one group are combined with AND.
- Groups in
filterGroupsare combined with OR. filters(without groups) is a single AND list.
Operators
| Operator | Matches records whose property… |
|---|---|
| EQ | is equal to value. |
| NEQ | has a value that is different from value. |
| CONTAINS_TOKEN | contains value anywhere in the text (not case sensitive for most data). |
| CONTAINS | same as CONTAINS_TOKEN. |
| GT / GTE | is greater than / greater than or equal to value. |
| LT / LTE | is less than / less than or equal to value. |
| IN | is one of the values. value is an array, or a comma-separated string. |
| IN_OR_EMPTY | is one of the values, or has no value at all. value is an array. |
Note
Values are stored as text, so
GT, GTE, LT and LTE compare text. They work well for ISO dates such as 2026-11-01; for numbers, compare values with the same number of digits.Free-text query
query finds records where any of these properties contains the text:
| Object type | Properties searched |
|---|---|
| 0-1 contacts | firstname, lastname, email, phone, company |
| 0-2 companies | name, domain, website, phone |
| 0-3 deals | dealname, pipeline, dealstage, description |
| custom objects | name |
You can send query together with filters: a record must then match both.
More examples
Contacts named Ali, or anyone at example.com
Request Body · json
{
"filterGroups": [
{
"filters": [
{
"propertyName": "firstname",
"operator": "EQ",
"value": "Ali"
}
]
},
{
"filters": [
{
"propertyName": "email",
"operator": "CONTAINS_TOKEN",
"value": "@example.com"
}
]
}
]
}Deals in one of two stages
Request Body · json
{
"filters": [
{
"propertyName": "dealstage",
"operator": "IN",
"value": [
"appointmentscheduled",
"qualifiedtobuy"
]
}
]
}Free text
Request Body · json
{
"query": "khan"
}Notes
- All matching records are returned in one reply, and
totalis their number. Narrow your filters for large results. - Sorting (
sorts),limitand theaftercursor are not supported yet; leave them out. - Use
value(notvalues) for the list of anINfilter.