Filtering

Simple attribute filters

Result set may be narrowed to records satisfying some condition. Filtering is done on per-attribute basis. Only items whose attributes meet given conditions are returned.

Basic filter consists of two elements: description of the attribute and the condition attribute with given name must meet. Let's consider query only for companies. This means only records whose is_organisation attribute is set to true should be returned.

Note that after adding filtering total_count value has changed. This always returns number of items matching query. If query contains no filters, it returns number of all records user sending the request has access to. When additional filters are applied, total_count returns number of items matched by the filters, that the user has access to.

Be aware that for tasks, the account's time zone will be applied to all datetime properties. Any datetime offset added to the date filter will be disregarded.

Fetch contacts

POST /v3/contacts/search

Authorization: Bearer $ACCESS_TOKEN
Content-Type: application/json

{
  "items": [
    {
      "data": {
        "query": {
          "filter": {
          	"filter": {
          		"attribute": {
          			"name": "is_organisation"
          		},
          		"parameter": {
          			"eq": true
          		}
          	}
          },
          "projection": [
            {
              "name": "is_organisation"
            },
            {
                "name": "display_name"
            }
          ]
        }
      },
      "per_page": 1
    }
  ]
}

Content-Type: application/json; charset=UTF-8

{
    "items": [
        {
            "successful": true,
            "items": [
                {
                    "data": {
                        "id": 9876,
                        "display_name": "Large Company",
                        "is_organisation": true,
                        "version": 55
                    },
                    "meta": {
                        "type": "contact"
                    }
                }
            ],
            "meta": {
                "count": 1,
                "http_status": "200 OK",
                "links": {
                    "next_page": "nextPageToken=="
                },
                "total_count": 5634,
                "type": "collection"
            }
        }
    ]
}

---

Complex filters

Filters can get arbitrarily complex, allowing to implement very wide range of custom behaviors. Let's now consider example data quality check pipeline, in which an organization wants to check how many leads without any phone number were added by given sales rep. This can be expressed by following filter query.

filter contains one and array element, which consists of two elements:

• eq filter on owner.name attribute, which only matches leads whose owner's name is John Doe
• another and filter, which only matches leads that simultaneously meet two nested conditions:
  • phone_numbers.phone attribute is missing AND
  • phone_number.mobile attribute is missing

Fetch contacts

POST /v3/contacts/search

Authorization: Bearer $ACCESS_TOKEN
Content-Type: application/json

{
  "items": [
    {
      "data": {
        "query": {
          "filter": {
            "and": [
              {
                "filter": {
                  "attribute": {
                    "name": "owner.name"
                  },
                  "parameter": {
                    "eq": "John Doe"
                  }
                }
              },
              {
                "and": [
                  {
                    "filter": {
                      "attribute": {
                        "name": "phone_numbers.phone"
                      },
                      "parameter": {
                        "missing": true
                      }
                    }
                  },
                  {
                    "filter": {
                      "attribute": {
                        "name": "phone_numbers.mobile"
                      },
                      "parameter": {
                        "missing": true
                      }
                    }
                  }
                ]
              }
            ]
          }
        }
      }
    }
  ]
}

---

Filters can generally be divided into two categories:

Attribute filters, that describe condition a single attribute should meet. There are 10 types of attribute filters:

• any - attribute must have one of provided values
• all - attribute must have all of provided values (only applies to array attributes)
• contains - string or keyword attribute must contain provided phrase
• missing - attribute value must not be set (same as is_null)
• starts_with - string or keyword attribute must start with provided phrase
• eq - attribute value must be same as provided one
• is_null - attribute value must not be set (same as missing)
• range - attribute value must be within specified range
• geo_distance - attribute point must be within specified range from some point (only applies to geo-point attributes)
• graph_expression - attribute value must be in result set of some graph expression (more about graph expressions in related section)

Compound filters, that aggregate or modify behavior of other filters (compound or attribute)

• and - describes array of filters, all of which must match in order for this filter to match
• or - describes array of filters, at least one of which must match in order for this filter to match
• not - wraps single filter, that must not match for this filter to mat

Not every combination of attribute type and filter type is legal, e.g. starts_with filter can be applied to string attributes, but not to date_time attributes. Contrary, range filter makes sense for date_time attributes but not for string ones.

More about legal filter/attribute types combinations in Query language description.