Query the contacts object to get all contacts with their attributes.
Sample query: get contacts with specified attributes
In this sample query, we will get the first 2 contacts in the audience with their first names, emails and IDs (keys). The contacts in the response will be sorted alphabetically by their first names.
query {
contacts(
orderBy: [{ field: "First name", sort: ASC }]
first: 2
) {
nodes {
attributes(selectByName: ["First name", "Email", "Key"]) {
name
value
}
}
}
}
{
"data": {
"contacts": {
"nodes": [
{
"attributes": [
{
"name": "Email",
"value": "[email protected]"
},
{
"name": "Key",
"value": "PISCX-098724242477"
},
{
"name": "First name",
"value": "Akira"
}
]
},
{
"attributes": [
{
"name": "Email",
"value": "[email protected]"
},
{
"name": "Key",
"value": "PISCX-098724242021"
},
{
"name": "First name",
"value": "Diego"
}
]
}
]
}
}
}
If you don't have the names of all available contact attributes, see Query the audience. In the sample response below, pay attention to two addressable attributes (Email and Cell phone) and Key.
query {
dataSets {
nodes {
attributes {
name
type
category
identifyAs {
key
channels
}
}
}
}
}
{
"data": {
"dataSets": {
"nodes": [
{
"attributes": [
{
"name": "Email",
"type": "TEXT",
"category": null,
"identifyAs": {
"key": null,
"channels": [
"EMAIL"
]
}
},
{
"name": "Key",
"type": "TEXT",
"category": null,
"identifyAs": {
"key": true,
"channels": null
}
},
{
"name": "Age",
"type": "NUMBER",
"category": null,
"identifyAs": null
},
{
"name": "Last purchase",
"type": "DATE",
"category": null,
"identifyAs": null
},
{
"name": "Cell Phone",
"type": "TEXT",
"category": "Contact information",
"identifyAs": {
"key": null,
"channels": [
"SMS"
]
}
},
{
"name": "First Name",
"type": "TEXT",
"category": "Contact information",
"identifyAs": null
},
{
"name": "Last Name",
"type": "TEXT",
"category": "Contact information",
"identifyAs": null
}
]
}
]
}
}
}
Sample query: filter contacts by their attributes
In the following query, we will filter the contacts by their unique IDs (keys) and request all available information for them.
query {
contacts(
filter: [
{
field: "Key"
in: [
"PISCX-098724242477"
"PISCX-098724242021"
]
}
]
) {
nodes {
attributes {
name
value
}
}
}
}
{
"data": {
"contacts": {
"nodes": [
{
"attributes": [
{
"name": "Email",
"value": "[email protected]"
},
{
"name": "Key",
"value": "PISCX-098724242477"
},
{
"name": "Cell phone",
"value": "+123456789012345"
},
{
"name": "Age",
"value": 24
},
{
"name": "Last purchase",
"value": "2024-06-20T14:34:19.919Z"
},
{
"name": "Last Name",
"value": null
},
{
"name": "First name",
"value": "Akira"
}
]
},
{
"attributes": [
{
"name": "Email",
"value": "[email protected]"
},
{
"name": "Key",
"value": "PISCX-098724242021"
},
{
"name": "Cell phone",
"value": "+123456789012000"
},
{
"name": "Age",
"value": 56
},
{
"name": "Last purchase",
"value": "2023-01-07T14:34:19.919Z"
},
{
"name": "Last Name",
"value": "García"
},
{
"name": "First name",
"value": "Diego"
}
]
}
]
}
}
}
Another way to filter contacts is using an addressable attribute such as email address or phone number.
query {
contacts(
filter: [{ field: "Email", eq: "[email protected]" }]
) {
nodes {
attributes {
name
value
}
}
}
}
{
"data": {
"contacts": {
"nodes": [
{
"attributes": [
{
"name": "Email",
"value": "[email protected]"
},
{
"name": "Key",
"value": "PISCX-098724242477"
},
{
"name": "Delivery address",
"value": "6097 Runolfsson Burgs Apt. 491"
},
{
"name": "Country",
"value": "Latvia"
},
{
"name": "City/Town",
"value": "Riga"
},
{
"name": "Cell Phone",
"value": "+371234567890001"
},
{
"name": "Name",
"value": "Diego"
},
{
"name": "Last Name",
"value": null
}
]
}
]
}
}
}
No matter which filtering option you use, keep in mind that one entry requires the eq input field. For multiple entries, usein.
filter: [
{
field: "Cell phone"
eq: "+541130000000"
}
]
filter: [
{
field: "Cell phone"
in: [
"+541130000000"
"+541230000000"
]
}
]
More filtering ideas
Find contacts with Gmail email addresses
filter: [
{
field: "EMAIL",
contains: "gmail"
}
]
Find contacts who haven't provided their email addresses
filter: [
{
field: "EMAIL",
blank: true
}
]
Find contacts who have provided their phone numbers
filter: [
{
field: "Cell phone",
blank: false
}
]
Arguments
Arguments supported by the contacts object:
| Argument | Nested field | Values | Required? | Definition |
|---|---|---|---|---|
orderBy | field | String | Optional | Use this argument to sort contacts in the response. To get the list of all available contact attributes, use the dataSets query. |
sort | Either of the following values: - ASC- DESC | Optional | The sort order to use for contacts in the response | |
first | Integer | Optional | If you don't need the full list of contacts, you can specify how many contacts to return from the beginning of the list. | |
last | Integer | Optional | If you don't need the full list of contacts, you can specify how many contacts to return from the end of the list. | |
filter | field | String | Optional | The name of the contact attribute to use for filtering |
in | Depends on the contact attribute | Optional | "Is one of the following." | |
eq | Depends on the contact attribute | Optional | "Equals." | |
blank | Boolean | Optional | "Is or isn't blank (depending on the value)" | |
contains | String | Optional | "Contains the specified text" |
Fields
Fields returned by the contacts query:
| Field | Required? | Values | Definition |
|---|---|---|---|
totalCount | Optional | Integer | The total number of contacts in the audience |
nodes | Required | See nested fields | |
tracking | Optional | See nested fields |
Fields nested inside the nodes field:
| Field | Nested field | Required? | Values | Definition |
|---|---|---|---|---|
attributes | value | Required | Depends on the type of contact attribute. | The value set to the contact attribute |
name | Optional | String | The name of a contact attribute | |
type | Optional | One of the following values: - TEXT- NUMBER- BOOLEAN- DATE | The data format of the contact attribute |
Fields nested inside the tracking field (all of them are optional)
| Field | Values | Definition |
|---|---|---|
createdAt | A date-time string at UTC, such as 2023-12-03T09:54:33Z | When the contact was added to the audience |
createdBy | String | The user who added the contact to the audience. |
lastModifiedAt | A date-time string at UTC, such as 2023-12-03T09:54:33Z | When the contact was modified last time |
lastModifiedBy | String | The user who modified the contact last time |
Possible errors
| Error code | Definition |
|---|---|
FAILED_FETCH_CONTACT |