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.

These filters use the ContactRule input type.

query FilterContacts($email: JSON!, $minScore: Float!) {
  contacts(filter: [
    { field: "Email Address", eq: $email }
    { field: "Score",         gt: $minScore }
  ]) {
    nodes {
      attributes(selectByName: ["Email Address", "Score"]) {
        name
        value
      }
    }
  }
}

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.

Many operators support a negated form by prefixing with n (for example, neq negates eq). Several date operators are relative to today rather than a fixed value.

📘
The JSON scalar
The value field accepts any JSON value — string, number, boolean, array, or object. Declare variables as JSON!, not String!. This applies to the eq, neq, in, and nin operators only — other operators use their own specific types (see the Value type column below).

query FindContact($emailValue: JSON!) {
  contacts(filter: [{ field: "Email Address", eq: $emailValue }]) {
    nodes {
      attributes(selectByName: ["Email Address"]) {
        name
        value
      }
    }  
  }
}

Declaring String! causes the error: Variable "$emailValue" of type "String!" used in position expecting type "JSON". The value itself does not change — a JSON string is already valid JSON.

Operator	Value type	Description
`eq`	`JSON`	Filter for exact matches
`neq`	`JSON`	Filter for values not equal to this value
`in`	`[JSON!]`	Is in the list of values
`nin`	`[JSON!]`	Is not in the list of values
`contains`	`String`	Filter for values containing this text
`ncontains`	`String`	Filter for values not containing this text
`startsWith`	`String`	Filter for values starting with this text
`nstartsWith`	`String`	Filter for values not starting with this text
`endsWith`	`String`	Filter for values ending with this text
`nendsWith`	`String`	Filter for values not ending with this text
`after`	`String`	Is after a given date (RFC 3339 format)
`before`	`String`	Filter for dates before this value (RFC 3339 format)
`containsOneOf`	`[String!]`	Filter for values containing any of these texts
`ncontainsOneOf`	`[String!]`	Filter for values not containing any of these texts
`startsWithOneOf`	`[String!]`	Filter for values starting with any of these texts
`nstartsWithOneOf`	`[String!]`	Filter for values not starting with any of these texts
`endsWithOneOf`	`[String!]`	Filter for values ending with any of these texts
`nendsWithOneOf`	`[String!]`	Filter for values not ending with any of these texts
`eqOneOf`	`[String!]`	Filter for values matching any of these options
`neqOneOf`	`[String!]`	Filter for values not matching any of these options
`lt`	`Float`	Is less than
`lte`	`Float`	Is less than or equal to
`gt`	`Float`	Is greater than
`gte`	`Float`	Is greater than or equal to
`year`	`Float`	Is in the given year
`month`	`Float`	Is in the given month (1-12)
`day`	`Float`	Is in the given day (1-31)
`blank`	`Boolean`	Filter for empty/non-empty values
`isToday`	`Boolean`	Filter for dates matching today
`isAfterToday`	`Boolean`	Filter for dates after today
`isBeforeToday`	`Boolean`	Filter for dates before today
`isAnniversaryToday`	`Boolean`	Filter for yearly anniversaries occurring today
`arrayEmpty`	`Boolean`	Filter for empty/non-empty array values
`between`	`ValueRangeInput`	Filter for values within a range
`anniversary`	`ValueWithinInput`	Filter for anniversary exactly the provided number of days/weeks/months ago
`exactly`	`ValueWithinInput`	Filter for dates exactly the provided number of days/weeks/months ago/away
`nexactly`	`ValueWithinInput`	Filter for dates not exactly the provided number of days/weeks/months ago
`withinLast`	`ValueWithinInput`	Filter for dates within the provided number of last days/weeks/months
`nwithinLast`	`ValueWithinInput`	Filter for dates not within the provided number of last days/weeks/months
`withinNext`	`ValueWithinInput`	Filter for dates within the provided number of next days/weeks/months
`nwithinNext`	`ValueWithinInput`	Filter for dates not within the provided number of next days/weeks/months
`withinLastRange`	`DateValueRangeInput`	Filter for dates within the provided range of last days/weeks/months
`and`	`[ContactRule!]`	Combine multiple conditions with AND logic
`or`	`[ContactRule!]`	Combine multiple conditions with OR logic
`count`	`[ContactRule!]`	Filter based on the count of matching sub-conditions
`not`	`ContactRule`	Negate a condition

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

Complete reference

The JSON scalar

Examples

Related pages