Query the contacts object to get all contacts with their attributes and consent information.

Typical usage:

Retrieve contact lists with specific attributes for data analysis or export
Filter contacts by demographic information
Access contact information for customer service purposes

Running the query

If you haven't used our API before, see Using the Connect API for instructions. It explains how to authenticate your calls and suggests some tools for testing.

Basic query structure

query {
  contacts {
    totalCount
    nodes {
      attributes {
        name
        value
      }
    }
  }
}

Query arguments (all optional)

after: String - Cursor for forward pagination (use with first)
before: String - Cursor for backward pagination (use with last)
filter: Array of objects - Filter contacts based on criteria
first: Integer - Number of results from beginning
last: Integer - Number of results from end
orderBy: Array of objects - Sort contacts by specific attributes

Pagination

The contacts query uses cursor-based pagination. Use after and before cursors to navigate through result pages:

Forward pagination: Use first with after cursor from previous page's pageInfo.endCursor.
Backward pagination: Use last with before cursor from previous page's pageInfo.startCursor.

Pagination example

Get first page

query {
  contacts(first: 3) {
    pageInfo {
      endCursor
      hasNextPage
    }
    nodes {
      attributes(selectByName: ["First Name", "Email"]) {
        name
        value
      }
    }
  }
}

{
  "data": {
    "contacts": {
      "pageInfo": {
        "endCursor": "YXJyYXljb25uZWN0aW90000=",
        "hasNextPage": true
      },
      "nodes": [
        {
          "attributes": [
            {
              "name": "First Name",
              "value": "Sarah"
            },
            {
              "name": "Email",
              "value": "[email protected]"
            }
          ]
        },
        {
          "attributes": [
            {
              "name": "First Name",
              "value": "James"
            },
            {
              "name": "Email",
              "value": "[email protected]"
            }
          ]
        },
        {
          "attributes": [
            {
              "name": "First Name",
              "value": "Lucas"
            },
            {
              "name": "Email",
              "value": "[email protected]"
            }
          ]
        }
      ]
    }
  }
}

Get next page using cursor from previous response

query {
  contacts(first: 3, after: "YXJyYXljb25uZWN0aW90000=") {
    pageInfo {
      endCursor
      hasNextPage
    }
    nodes {
      attributes(selectByName: ["First Name", "Email"]) {
        name
        value
      }
    }
  }
}

{
  "data": {
    "contacts": {
      "pageInfo": {
        "endCursor": "YXJyYXljb25uZWN0aW9u1111",
        "hasNextPage": true
      },
      "nodes": [
        {
          "attributes": [
            {
              "name": "First Name",
              "value": "Isabella"
            },
            {
              "name": "Email",
              "value": "[email protected]"
            }
          ]
        },
        {
          "attributes": [
            {
              "name": "First Name",
              "value": "Mason"
            },
            {
              "name": "Email",
              "value": "[email protected]"
            }
          ]
        },
        {
          "attributes": [
            {
              "name": "First Name",
              "value": "Ali"
            },
            {
              "name": "Email",
              "value": "[email protected]"
            }
          ]
        }
      ]
    }
  }
}

"Filter" object

See Filtering options for contacts.

"Order by" object

field (required): String - The name of the contact attribute to sort by. If you don't have the names of all available contact attributes, see Query the audience.
sort: Enum - The sort order. Valid values: ASC (ascending), DESC (descending). Default: ASC.

Response structure

The contacts query returns a JSON response with this structure:

data: Object - Root response object
- contacts: Object - Contains query results with the following fields:
  - nodes: Array - Individual contact objects (see Core contact fields below)
  - pageInfo: Object - Pagination metadata (see Pagination fields below)
  - totalCount: Integer - Total number of contacts matching the filter criteria

Pagination fields

count: Integer - Number of items on this page
endCursor: String or null - Cursor of last item on this page
hasNextPage: Boolean - More items available after this page
hasPreviousPage: Boolean - More items available before this page
startCursor: String or null - Cursor of first item on this page

Core contact fields

attributes: Array - Contact attribute data (see Attribute fields below)
consent: Object - Consent preferences (see Consent fields below)
tracking: Object - Audit information (see Tracking fields below)

Attribute fields

The attributes field accepts optional parameters to filter which attributes are returned:

selectByChannel: Enum - Return only attributes for a specific communication channel. Valid values: EMAIL, SMS, WHATSAPP. For example, if you submit EMAIL, you will get the Email Address attribute in the response.
selectByName: Array of strings - Contact attributes to return

Each attribute object contains:

name: String - The name of the contact attribute
type: Enum - The data type of the attribute. Valid values: TEXT, NUMBER, BOOLEAN, DATE.
value: Depends on attribute type - The value of the contact attribute

Consent fields

channels: Array - Consent status by channel (see fields below)
- channel: Enum (required) - The communication channel. Valid values: EMAIL, SMS, WHATSAPP.
- status: Enum (required) - The consent status for the channel. Valid values: OPT_IN, OPT_OUT, OPT_IN_UNVERIFIED.
consentGroups: Array - Consent preferences per consent group (see fields below)
- id: String (required) - Channel identifier
- channels: Array - Channels in the consent group. Objects in the array support the following fields:
  - channel: Enum (required) - The communication channel. Valid values: EMAIL, SMS, WHATSAPP.
  - status: Enum (required) - The consent status for the channel. Valid values: OPT_IN, OPT_OUT, OPT_IN_UNVERIFIED.

Notes:

If your marketing team manage consent by adding contacts to consent groups, use the consentGroups field. If they manage consent on the per-channel basis, use channels.
The channels field supports an optional enum parameter for filtering: selectByChannel. Valid values: EMAIL, SMS, WHATSAPP.

consent {
  channels(selectByChannel: EMAIL) {
    channel
    status
  }
}

The consentGroups field supports an optional parameter for filtering: selectById. Type: array of strings. To get the IDs of consent groups in your audience, use the dataSets query (instructions).

consent {
  consentGroups(selectById: ["cc5f4fdd-6d2f-5b1e-bcdc", "e360eebf-d9e8-519d-958c"]) {
    id
    channels {
      channel
      status
    }
  }
}

Tracking fields

createdAt: String - ISO 8601 timestamp when the contact was added to the audience. Example: 2024-12-03T09:54:33Z.
createdBy: String - The user who added the contact to the audience
lastModifiedAt: String - ISO 8601 timestamp when the contact was modified last time. Example: 2024-12-03T09:54:33Z.
lastModifiedBy: String - The user who last modified the contact

Examples

B2B campaign for corporate accounts

Filter by specific company email domains to reach decision-makers at target organizations.

query {
  contacts(
    first: 100
    filter: [
      {
        or: [
          { field: "Email", endsWith: "@company.com" }
          { field: "Email", endsWith: "@enterprise.com" }
          { field: "Email", endsWith: "@corp.net" }
        ]
      }
    ]
  ) {
    pageInfo {
      hasNextPage
      endCursor
    }
    nodes {
      attributes(selectByName: ["First name", "Last name", "Email", "Company"]) {
        name
        value
      }
    }
    totalCount
  }
}

Regional store promotions announcement

Find contacts in South Carolina who have selected a specific store as their preferred location.

query {
  contacts(
    first: 100
    filter: [
      {
        field: "City"
        eq: "Charleston"
      }
      {
        field: "Favorite Store"
        eq: "Marion Square"
      }
    ]
    orderBy: [
      {
        field: "First Name"
      }
    ]
  ) {
    pageInfo {
      hasNextPage
      endCursor
    }
    nodes {
      attributes(selectByName: ["First Name", "Phone Number", "City", "State", "Favorite store"]) {
        name
        value
      }
    }
    totalCount
  }
}

Birthday campaign for November

Retrieve contacts with birthdays in November for a birthday promotion campaign. Review consent status in the response to ensure compliance before sending.

query {
  contacts(
    first: 100
    filter: [
      {
        field: "Birthday"
        month: 11
      }
    ]
  ) {
    pageInfo {
      hasNextPage
      endCursor
    }
    nodes {
      attributes(selectByName: ["First name", "Email", "Birthday"]) {
        name
        value
      }
      consent {
        channels(selectByChannel: EMAIL) {
          channel
          status
        }
      }
    }
    totalCount
  }
}

Find contacts by their emails

query {
  contacts(filter: [{ field: "Email", eq: "[email protected]" }]) {
    nodes {
      attributes {
        name
        value
      }
    }
  }
}

query {
  contacts(
    filter: [
      { field: "Email", in: ["[email protected]", "[email protected]"] }
    ]
  ) {
    nodes {
      attributes {
        name
        value
      }
    }
  }
}