The contacts query supports an extensive selection of filters to help you identify high-value customers, find contacts due for re-engagement, generate compliance reports, export contact data to external platforms and more.

For example, you can identify contacts who are between 46 and 54 years old and live in Ontario, Canada.

query {
  contacts(
    filter: [
      {
        and: [
          {
            field: "Birthday"
            between: {
              from: "1971-01-01T00:00:00.000Z"
              to: "1979-01-01T00:00:00.000Z"
            }
          }
          { field: "City", eq: "Ontario" }
        ]
      }
    ]
  ) {
    nodes {
      attributes(selectByName: ["First name", "Email", "Birthday"]) {
        name
        value
      }
    }
    totalCount
  }
}

Complete reference

Each filter object in the contacts query can contain:

field (required): String - The name of the contact attribute to filter by. If you don't have the names of all available contact attributes, see Query the audience.

Text operators

blank: Boolean - Filter for empty/non-empty values
contains: String - Filter for values containing this text
containsOneOf: Array of strings - Filter for values containing any of these texts
endsWith: String - Filter for values ending with this text
endsWithOneOf: Array of strings - Filter for values ending with any of these texts
eq: String - Filter for exact matches
in: Array - Is in the list of values
ncontains: String - Filter for values not containing this text
ncontainsOneOf: Array of strings - Filter for values not containing any of these texts
nendsWith: String - Filter for values not ending with this text
nendsWithOneOf: Array of strings - Filter for values not ending with any of these texts
neq: String - Filter for values not equal to this value
nin: Array - Is not in the list of values
nstartsWith: String - Filter for values not starting with this text
nstartsWithOneOf: Array of strings - Filter for values not starting with any of these texts
startsWith: String - Filter for values starting with this text
startsWithOneOf: Array of strings - Filter for values starting with any of these texts

Number operators

between: Object - Filter for values within a range
- from (required): Number - Lower bound of the range
- to (required): Number - Upper bound of the range
blank: Boolean - Filter for empty/non-empty values
eq: Number - Filter for exact matches
gt: Number - Is greater than
gte: Number - Is greater than or equal to
in: Array - Is in the list of values
lt: Number - Is less than
lte: Number - Is less than or equal to
neq: Number - Filter for values not equal to this value
nin: Array - Is not in the list of values

Date operators

after: String - Is after a given date (ISO 8601 format)
anniversary: Object - Filter for anniversary exactly the provided number of days/weeks/months ago
- quantity (required): Number - The numeric quantity
- period (required): Enum - The time period. Valid values: days, weeks, months.
before: String - Filter for dates before this value (ISO 8601 format)
between: Object - Filter for values within a range
- from (required): String - Lower bound of the range
- to (required): String - Upper bound of the range
blank: Boolean - Filter for empty/non-empty values
day: Integer - Is in the given day (1-31)
eq: Varies - Filter for exact matches
eqOneOf: Array of strings - Filter for values matching any of these options
exactly: Object - Filter for dates exactly the provided number of days/weeks/months ago/away
- quantity (required): Number - The numeric quantity
- period (required): Enum - The time period. Valid values: days, weeks, months
isAfterToday: Boolean - Filter for dates after today
isAnniversaryToday: Boolean - Filter for yearly anniversaries occurring today
isBeforeToday: Boolean - Filter for dates before today
isToday: Boolean - Filter for dates matching todayv+
month: Integer - Is in the given month (1-12)
neq: Varies - Filter for values not equal to this value
neqOneOf: Array of strings - Filter for values not matching any of these options
nexactly: Object - Filter for dates not exactly the provided number of days/weeks/months ago
- quantity (required): Number - The numeric quantity
- period (required): Enum - The time period. Valid values: days, weeks, months.
nwithinLast: Object - Filter for dates not within the provided number of last days/weeks/months
- quantity (required): Number - The numeric quantity
- period (required): Enum - The time period. Valid values: days, weeks, months
nwithinNext: Object - Filter for dates not within the provided number of next days/weeks/months
- quantity (required): Number - The numeric quantity
- period (required): Enum - The time period. Valid values: days, weeks, months
withinLast: Object - Filter for dates within the provided number of last days/weeks/months
- quantity (required): Number - The numeric quantity
- period (required): Enum - The time period. Valid values: days, weeks, months
withinLastRange: Object - Filter for dates within the provided range of last days/weeks/months
- from (required): Number - Starting quantity
- to (required): Number - Ending quantity
- period (required): Enum - The time period. Valid values: days, weeks, months
withinNext: Object - Filter for dates within the provided number of next days/weeks/months
- quantity (required): Number - The numeric quantity
- period (required): Enum - The time period. Valid values: days, weeks, months
year: Integer - Is in the given year

Logical operators

and: Array of objects - Combine multiple conditions with AND logic
not: Object - Negate a condition
or: Array of objects - Combine multiple conditions with OR logic

Examples

Find corporate contacts using selected domains

filter: [
      {
        or: [
          { field: "Email", endsWith: "@company.com" }
          { field: "Email", endsWith: "@enterprise.com" }
          { field: "Email", endsWith: "@corp.net" }
        ]
      }
    ]

Find contacts without email addresses

filter: [
  { 
    field: "Email"
    blank: true 
  }
]

Find contacts who were born in January

filter: [
  { 
    field: "Birthday"
    month: 1 
  }
]

Query contacts

Filtering options for contacts