Meta Pixel
RubikChat
RubikChat
Get Started Free

No credit card required · 14-day free trial

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

NameTypeRequiredDescription
objectTypestringrequiredObject type id (0-1 contacts, 0-2 companies, 0-3 deals, 2-… custom objects) or its name, e.g. contacts.

Request Body

NameTypeRequiredDescription
filterGroupsarrayoptionalGroups of filters. A record matches when it matches every filter of at least one group.
filtersarrayoptionalA single list of filters that must all match. Use it instead of filterGroups when you need no OR.
querystringoptionalFree 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

FieldTypeDescription
propertyNamestringThe internal name of the property, e.g. email.
operatorstringOne of the operators below. Defaults to EQ.
valuestring | arrayThe value to compare with. An array for IN and IN_OR_EMPTY.
  • Filters inside one group are combined with AND.
  • Groups in filterGroups are combined with OR.
  • filters (without groups) is a single AND list.

Operators

OperatorMatches records whose property…
EQis equal to value.
NEQhas a value that is different from value.
CONTAINS_TOKENcontains value anywhere in the text (not case sensitive for most data).
CONTAINSsame as CONTAINS_TOKEN.
GT / GTEis greater than / greater than or equal to value.
LT / LTEis less than / less than or equal to value.
INis one of the values. value is an array, or a comma-separated string.
IN_OR_EMPTYis 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 typeProperties searched
0-1 contactsfirstname, lastname, email, phone, company
0-2 companiesname, domain, website, phone
0-3 dealsdealname, pipeline, dealstage, description
custom objectsname

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 total is their number. Narrow your filters for large results.
  • Sorting (sorts), limit and the after cursor are not supported yet; leave them out.
  • Use value (not values) for the list of an IN filter.