To update consent statuses for your contacts, use the updateContacts mutation.

You can do it by adding contacts to respective consent groups or by specifying their preferences on a per-channel basis. The way you format these mutations depends on the approach your marketing team pursues.

Option A: update statuses within a consent group

The following example demonstrates how to add a contact to several consent groups or to update existing statuses within a consent group. Note that we set the OPT_IN status for the first consent group (all channels will be updated). In the second consent group, we limit preference to a particular channel within the consent group (EMAIL).

mutation {
  updateContacts(
    updateContactInputs: [
      {
        key: "DDE_98716455"
        to: {
          consent: {
            consentGroups: [
              {
                consentGroupId: "97660d76-02d8-5fd6-xxxx-000000000000"
                status: OPT_OUT
              }
              {
                consentGroupId: "97660d76-02d8-5fd6-xxxx-00000000001"
                channels: [{ channel: EMAIL, status: OPT_IN }]
              }
            ]
          }
        }
      }
    ]
  ) {
    modifiedCount
  }
}

{
  "data": {
    "updateContacts": {
      "modifiedCount": 1
    }
  }
}

Option B: update consent statuses per channel

In this example, we will subscribe one contact to emails and unsubscribe another one from text messages.

mutation {
  updateContacts(
    updateContactInputs: [
      {
        key: "DDJ_98716421"
        to: {
          attributes: [
            { name: "Email Address", value: "[email protected]" }
          ]
          consent: { channels: { channel: EMAIL, status: OPT_IN } }
        }
      }
      {
        key: "DEW_98716421"
        to: {
          consent: { channels: { channel: SMS, status: OPT_OUT } }
        }
      }
    ]
  ) {
    modifiedCount
  }
}

{
  "data": {
    "updateContacts": {
      "modifiedCount": 2
    }
  }
}

If your audience doesn't have the Contact key attribute defined, then you must rely on addressable attributes for contact identification (emails and phone numbers).

mutation {
  updateContacts(
    updateContactInputs: [
      {
        addressable: [{ field: "Email", eq: "[email protected]" }]
        to: {
          consent: {
            consentGroups: [
              {
                consentGroupId: "021f18c8-34ef-5831-0000-919191919191"
                status: OPT_IN
              }
            ]
          }
        }
      }
      {
        addressable: [{ field: "Phone Number", eq: "+142490300000" }]
        to: {
          consent: {
            consentGroups: [
              {
                consentGroupId: "021f18c8-34ef-5831-0000-919191919111"
                channels: [{ channel: SMS, status: OPT_IN_UNVERIFIED }]
              }
            ]
          }
        }
      }
    ]
  ) {
    modifiedCount
  }
}

{
  "data": {
    "updateContacts": {
      "modifiedCount": 2
    }
  }
}

Arguments

The updateContacts mutation contains the updateContactInputs argument at the top level. It's an array of objects. Each contact requires its own object.

Here are the input fields supported by objects within the updateContactInputs array.

Field	Values	Values	Definition
`addressable`	Array of objects	Optional	You must add this field to the mutation if your audience doesn't have the Contact key attribute. The array can contain either one object (email address or phone number) or two objects (email address and phone number). ⚠️ Do not use this field together with `key`.
`key`	String	Optional	The contact key assigned to the contact. ⚠️ Do not use this field together with `addressable`.
`to`	Array of objects	Required	Add an object for each contact attribute you want to update.

Fields nested into the addressable field (both of them are required):

Field	Values	Definition
`field`	String	The name of the addressable attribute to use for identification
`eq`	String	The value of the addressable attribute for the contact

Fields supported by objects within the to field:

Field	Nested field	Values	Definition
`attributes`	`name`	String	The name of the contact attribute you want to update
	`value`	Depends on the type of contact attribute.	The new value of the contact attribute
`consent`	`channels`	Array of objects	Use this field if your marketing team manages consent by the channel. Each channel requires its own object.
	`consentGroups`	Array of objects	Use this field if your marketing team manages consent on the consent group basis. Each consent group requires its own object.

Fields supported by objects within the channels field (both of them are required):

Field	Values	Definition
`channel`	Enumeration. Valid values: - `EMAIL` - `SMS` - `WHATSAPP`	The type of communication channel
`status`	Enumeration. Valid values: - `OPT_IN` - `OPT_OUT` - `OPT_IN_UNVERIFIED`	Indicates if the contact has agreed to receive communication through the channel.

Fields supported by objects within the consentGroups field

Field	Nested field	Values	Definition
`channels`	`channel`	Enumeration. Valid values: - `EMAIL` - `SMS` - `WHATSAPP`	A communication channel associated with the consent group. ⚠️ Don't use the `channels` field together with `status`.
	`status`	Enumeration. Valid values: - `OPT_IN` - `OPT_OUT` - `OPT_IN_UNVERIFIED`	The contact's consent status in relation to the communication channel
`consentGroupId`		String	The ID of the consent group the contact has been added to
`status`		Enumeration. Valid values: - `OPT_IN` - `OPT_OUT` - `OPT_IN_UNVERIFIED`	The contact's status within the consent group (applies to all of its channels). ⚠️ Don't use this field together with `channels`.

Fields

Fields returned by the updateContacts mutation:

Field	Values	Required?	Definition
`modifiedCount`	Integer	Required	The number of contacts that have been updated

Possible error messages

Here are error messages related to consent:

CHANNEL_NOT_DEFINED
CHANNELS_ALREADY_ASSIGNED
CHANNELS_DUPLICATE_PROVIDED
CONSENT_GROUP_NOT_FOUND
CONSENT_UPDATE_FOR_UNSET_ATTRIBUTE
INVALID_CHANNEL_TYPE
INVALID_CONSENT_FIELD_NAME

For other error messages, see Update contacts.