Skip to navigation
Search & Reporting

Advanced Filtering

Use the Advanced Filtering API to find Leads, Contacts, Opportunities, Activities and other objects matching any combination of filters.
View as Markdown

The Advanced Filtering API finds objects matching a structured query sent to Search objects with filters (POST /api/v1/data/search/). It’s the API behind the filters on the Leads, Contacts and Opportunities pages in Close.

This page is a short tutorial. The endpoint reference explains how to build queries and documents every parameter, query type and condition, as well as dates, results and pagination. Advanced Filtering Fields lists the fields you can filter by for each object type.

Tutorial

Let’s find all Contacts with “CEO” in their title. The request body looks like this:

{
  "query": {
    "type": "and",
    "queries": [
      {
        "type": "object_type",
        "object_type": "contact"
      },
      {
        "type": "field_condition",
        "field": {
          "type": "regular_field",
          "object_type": "contact",
          "field_name": "title"
        },
        "condition": {
          "type": "text",
          "mode": "full_words",
          "value": "CEO"
        }
      }
    ]
  },
  "_fields": {
    "contact": ["id", "name", "title"]
  }
}

The and query combines an object_type query, which asks for Contacts, with a field_condition query, which asks for Contacts whose title contains the word “CEO”. _fields asks for the Contacts’ id, name and title.

Here’s an example response:

{
  "data": [
    {
      "__object_type": "contact",
      "id": "cont_PtENYt1P6sRWkcnqoGnIj6hcZammGPdVbTXJWqdTvpV",
      "name": "Lucille Bluth",
      "title": "CEO"
    },
    {
      "__object_type": "contact",
      "id": "cont_HjTcJFiNli2AKf5fioygQDVSpA9nJILI9SkKv3nBk0A",
      "name": "Steli Efti",
      "title": "CEO & Co-Founder"
    }
  ],
  "cursor": null
}

To filter by fields of another object, use a has_related query. For example, here are CEOs with at least one email address, at Leads whose Industry custom field is “Software as a service”:

{
  "query": {
    "type": "and",
    "queries": [
      {
        "type": "object_type",
        "object_type": "contact"
      },
      {
        "type": "field_condition",
        "field": {
          "type": "regular_field",
          "object_type": "contact",
          "field_name": "emails_count"
        },
        "condition": {
          "type": "number_range",
          "gte": 1
        }
      },
      {
        "type": "field_condition",
        "field": {
          "type": "regular_field",
          "object_type": "contact",
          "field_name": "title"
        },
        "condition": {
          "type": "text",
          "mode": "full_words",
          "value": "CEO"
        }
      },
      {
        "type": "has_related",
        "this_object_type": "contact",
        "related_object_type": "lead",
        "related_query": {
          "type": "field_condition",
          "field": {
            "type": "custom_field",
            "custom_field_id": "cf_B57sofuEB7OBneH86SJctTr7hfiAiQcgkGRbAQfha0Z"
          },
          "condition": {
            "type": "term",
            "values": ["Software as a service"]
          }
        }
      }
    ]
  }
}

This query introduces a few more concepts:

  • A number_range condition for a number field. gte: 1 means greater than or equal to 1.
  • A custom_field, which references a custom field by its ID. Find custom field IDs with the custom field endpoints, e.g. List Lead Custom Fields.
  • A term condition, which matches one of the choices of a choice custom field.
  • A has_related query, which matches Contacts whose Lead matches the related_query. Fields in the related_query belong to the related object type. Use it the other way around too, e.g. to find Leads with a Contact who has a title, or Leads with a call in the last week (activity.call).

Visual Query Builder

Instead of writing the JSON query by hand, you can build your query visually on the Leads Page or Contacts page in Close, and then copy the JSON query by clicking the triple-dot menu on the top right and selecting “Copy Filters”.

Advanced Filtering

Query types

TypeMatches
and, orObjects matching all, or at least one, of the given queries.
object_typeObjects of a type, e.g. lead, contact or activity.call.
field_conditionObjects whose field value satisfies a condition.
has_relatedObjects with a related object matching a query.
textObjects containing the given text in any text field, like the search bar in Close.
idA single object by its ID.
saved_search, any_of_saved_searchObjects matching one or more Smart Views.
in_statusLeads or Opportunities that were in any of the given statuses in a period.
match_allEvery object.

Field conditions

Which condition to use depends on the field’s value type, which Advanced Filtering Fields lists for every field.

Value typeConditions
text, email address, phone number, URLtext, multiple_text
one of a fixed set of values, choice custom fieldsterm
IDs of other objects (users, statuses, …)reference, and current_user for the requesting user
numbersnumber_range, number, multiple_numbers
durationsduration_range
dates and datetimesmoment_range, predefined_relative_date_range, fixed_date_range, exact_moment
booleansboolean
timezonestimezone_name, local_time
any fieldexists