Use the contacts query to check contacts' consent statuses. The query format depends on the approach your marketing team pursues. Some teams add their contacts to consent groups, others manage consent on the per-channel basis.
Option A: check statuses per consent group
In this example, we will check the presence in consent groups of the first two contacts. We will request the name, unique ID, phone number and email address of each contact.
query {
contacts(first: 2) {
nodes {
attributes(
selectByName: ["First Name", "Unique key", "SMS Phone Number", "Email"]
) {
name
value
}
consent {
consentGroups {
id
channels {
channel
status
}
}
}
}
}
}
{
"data": {
"contacts": {
"nodes": [
{
"attributes": [
{
"name": "First Name",
"value": "Alice"
},
{
"name": "Unique key",
"value": "PISCX-098724242433"
},
{
"name": "SMS Phone Number",
"value": "+123456789009876"
},
{
"name": "Email",
"value": "[email protected]"
}
],
"consent": {
"consentGroups": [
{
"id": "97660d76-02d8-5fd6-1xx1-0000000000000",
"channels": [
{
"channel": "SMS",
"status": "OPT_IN"
}
]
},
{
"id": "97660d76-02d8-5fd6-1xx1-0000000000000",
"channels": [
{
"channel": "EMAIL",
"status": "OPT_IN"
}
]
},
{
"id": "97660d76-02d8-5fd6-1xx1-0000000000000",
"channels": [
{
"channel": "EMAIL",
"status": "OPT_IN"
},
{
"channel": "SMS",
"status": "OPT_IN"
}
]
},
{
"id": "97660d76-02d8-5fd6-1xx1-0000000000000",
"channels": [
{
"channel": "EMAIL",
"status": "OPT_IN_UNVERIFIED"
}
]
}
]
}
},
{
"attributes": [
{
"name": "First Name",
"value": "Rich"
},
{
"name": "Unique key",
"value": "PISCX-098724242409"
},
{
"name": "SMS Phone Number",
"value": "+123456789009876"
},
{
"name": "Email",
"value": "[email protected]"
}
],
"consent": {
"consentGroups": [
{
"id": "97660d76-02d8-5fd6-1xx1-0000000000000",
"channels": [
{
"channel": "EMAIL",
"status": "OPT_IN"
},
{
"channel": "SMS",
"status": "OPT_OUT"
}
]
},
{
"id": "97660d76-02d8-5fd6-1xx1-0000000000000",
"channels": [
{
"channel": "EMAIL",
"status": "OPT_IN_UNVERIFIED"
}
]
},
{
"id": "97660d76-02d8-5fd6-1xx1-0000000000000",
"channels": [
{
"channel": "EMAIL",
"status": "OPT_IN_UNVERIFIED"
}
]
}
]
}
}
]
}
}
}
Here is how to get consent for a particular consent group:
- Get the IDs of available consent groups if you don't have them yet. For more information, see Query an audience.
query {
dataSets {
nodes {
consentGroups {
name
id
}
}
}
}
{
"data": {
"dataSets": {
"nodes": [
{
"consentGroups": [
{
"name": "Newsletters",
"id": "97660d76-02d8-5fd6-1aa1-000000000000"
},
{
"name": "Promotions",
"id": "97660d76-02d8-5fd6-1aa1-000000000000"
},
{
"name": "Information",
"id": "97660d76-02d8-5fd6-1aa1-000000000000"
},
{
"name": "Custom",
"id": "97660d76-02d8-5fd6-1aa1-000000000000"
}
]
}
]
}
}
}
- Copy the ID of the consent group you need data for.
- Run the
contactsquery. Submit the ID of the consent group as an argument (selectById). In the current example, we will limit the number of results to 2.
query {
contacts(first: 2) {
nodes {
attributes(
selectByName: ["First Name", "Unique key", "SMS Phone Number", "Email"]
) {
name
value
}
consent {
consentGroups(selectById: ["64317b77-8c30-5fb3-9371-11111ddddd11", "64317b77-8c30-5fb3-9371-11111ddddd11"]) {
id
channels {
channel
status
}
}
}
}
}
}
{
"data": {
"contacts": {
"nodes": [
{
"attributes": [
{
"name": "First Name",
"value": "Alice"
},
{
"name": "Unique key",
"value": "PISCX-098724242433"
},
{
"name": "SMS Phone Number",
"value": "+123456789009876"
},
{
"name": "Email",
"value": "[email protected]"
}
],
"consent": {
"consentGroups": [
{
"id": "64317b77-8c30-5fb3-9371-11111ddddd11",
"channels": [
{
"channel": "EMAIL",
"status": "OPT_IN"
},
{
"channel": "SMS",
"status": "OPT_IN"
}
]
},
{
"id": "64317b77-8c30-5fb3-9371-11111ddddd11",
"channels": [
{
"channel": "EMAIL",
"status": "OPT_IN_UNVERIFIED"
}
]
}
]
}
},
{
"attributes": [
{
"name": "First Name",
"value": "Rich"
},
{
"name": "Unique key",
"value": "PISCX-098724242409"
},
{
"name": "SMS Phone Number",
"value": "+123456789009876"
},
{
"name": "Email",
"value": "[email protected]"
}
],
"consent": {
"consentGroups": [
{
"id": "64317b77-8c30-5fb3-9371-11111ddddd11",
"channels": [
{
"channel": "EMAIL",
"status": "OPT_IN_UNVERIFIED"
}
]
},
{
"id": "64317b77-8c30-5fb3-9371-11111ddddd11",
"channels": [
{
"channel": "EMAIL",
"status": "OPT_IN"
},
{
"channel": "SMS",
"status": "OPT_OUT"
}
]
}
]
}
}
]
}
}
}
Option B: check consent statuses per channel
In the following example, we will check if the last two contacts in the audience have agreed to receive communication from us.
query {
contacts(last: 2) {
nodes {
attributes(
selectByName: ["First Name", "Unique Key", "Email", "SMS Phone Number"]
) {
name
value
}
consent {
channels {
channel
status
}
}
}
}
}
{
"data": {
"contacts": {
"nodes": [
{
"attributes": [
{
"name": "Email",
"value": "[email protected]"
},
{
"name": "Unique Key",
"value": "PISCX-098724242477"
},
{
"name": "First Name",
"value": "Alice"
},
],
"consent": {
"channels": [
{
"channel": "SMS",
"status": "OPT_OUT"
},
{
"channel": "EMAIL",
"status": "OPT_IN"
}
]
}
},
{
"attributes": [
{
"name": "Email",
"value": "[email protected]"
},
{
"name": "Unique Key",
"value": "PISCX-098724242477"
},
{
"name": "First Name",
"value": "Diego"
},
{
"name": "SMS Phone Number",
"value": "+12345678900098"
}
],
"consent": {
"channels": [
{
"channel": "EMAIL",
"status": "OPT_IN"
},
{
"channel": "SMS",
"status": "OPT_IN"
}
]
}
}
]
}
}
}
To get consent for a particular channel, you must submit the name of the channel as an argument. In the current example, we will limit the number of results to 3.
query {
contacts(last: 2) {
nodes {
attributes(selectByName: ["First Name", "Unique Key", "Email address"]) {
name
value
}
consent {
channels(selectByChannel: EMAIL) {
channel
status
}
}
}
}
}
{
"data": {
"contacts": {
"nodes": [
{
"attributes": [
{
"name": "First Name",
"value": "Anna"
},
{
"name": "Email",
"value": "[email protected]"
},
{
"name": "Unique Key",
"value": "PISCX-098724242470"
}
],
"consent": {
"channels": [
{
"channel": "EMAIL",
"status": "OPT_IN"
}
]
}
},
{
"attributes": [
{
"name": "First Name",
"value": "Heather"
},
{
"name": "Email",
"value": "[email protected]"
},
{
"name": "Unique Key",
"value": "PISCX-098724242699"
}
],
"consent": {
"channels": [
{
"channel": "EMAIL",
"status": "OPT_IN"
}
]
}
}
]
}
}
}
Arguments
Optional arguments supported by the contacts query:
| Argument | Nested field | Values | Definition |
|---|---|---|---|
orderBy | field | String | Use this argument to sort contacts in the response. To get the list of all available contact attributes, use the Get all contact attributes query. |
sort | Either of the following values: - ASC- DESC | The sort order to use for contacts in the response | |
first | Integer | 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 | 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 | The name of the contact attribute to use for filtering |
in | Depends on the contact attribute | "Is one of the following." | |
eq | Depends on the contact attribute | "Equals." |
Fields
Fields returned by the contacts query:
| Field | Nested field | Required? | Values | Definition |
|---|---|---|---|---|
nodes | attributes | Optional | Array | Various contact attributes. For more information, see Get all contacts. |
consent | Optional | Array | Various consent-related settings |
Fields nested into the consent field:
| Field | Nested field - level 1 | Nested field - level 2 | Values | Definition |
|---|---|---|---|---|
channels | channel | Either of the following values: - EMAIL- SMS | The type of communication channel | |
status | One of the following values: - OPT_IN- OPT_OUT- OPT_IN_UNVERIFIED- null | Indicates if the contact has agreed to receive communication through the channel. | ||
consentGroups | id | The ID of a consent group that the contact belongs to | ||
channels | channel | Either of the following values: - EMAIL- SMS | A media channel associated with the consent group | |
status | One of the following values: - OPT_IN- OPT_OUT- OPT_IN_UNVERIFIED- null | The contact's opt-in status in the media channel |
Arguments supported by the channels field:
| Argument | Values | Required? | Definition |
|---|---|---|---|
selectByChannel | One of the following values: - EMAIL- SMS | Optional | Use this argument to get consent for a particular channel |
Arguments supported by the consentGroups field:
| Argument | Values | Required? | Definition |
|---|---|---|---|
selectById | ID | Optional | Use this argument to get consent for a particular consent group. To get all available IDs, use the Query an audience query. |
Possible error messages
| Error code | Definition |
|---|---|
FAILED_FETCH_SMS_CONSENT |