You can specify contacts' consent statuses when adding them to your audience. Use the Create contacts mutation with additional fields.

There are two approaches to registering consent for contacts:

by adding the contacts to respective consent groups
by subscribing them to channels.

These approaches are mutually exclusive. You cannot use both for the same contact.

Rules:

To create a contact, you must submit at least one addressable attribute for them (the one that has a channel defined).
To create a contact with the opt-in status, you must provide the addressable value for each channel that has the contact's consent. For example, to set consent for the Email channel, you must submit the contact's email address. For more information about consent statuses, see Consent.

Approach A: add contacts with consent group membership

The following example demonstrates how to add new contacts to your audience and register them in several consent groups. Note that we set the OPT_IN status for the first consent group. In the second consent group, we limit preference to a particular channel within the consent group (EMAIL).

mutation {
  createContacts(
    contactsInput: [
      {
        attributes: [
          { name: "Name", value: "Alice" }
          { name: "Last Name", value: "Brown" }
          { name: "Email", value: "[email protected]" }
        ]
        consent: {
          consentGroups: [
            { consentGroupId: "97660d76-02d8-5fd6-xxxx-000000000000", status: OPT_IN }
            {
              consentGroupId: "97660d76-02d8-5fd6-xxxx-000000000000"
              channels: { channel: EMAIL, status: OPT_IN_UNVERIFIED }
            }
          ]
        }
      }
    ]
    dataSetId: "4fe4136f-c007-44a3-b38f-92220xxxxxxxx"
  ) {
    items {
      contactId
    }
  }
}

{
  "data": {
    "createContacts": {
      "items": [
        {
          "contactId": "a364f922-2845-4718-9705-00000000y000"
        }
      ]
    }
  }
}

If you don't have the ID's of consent groups in your audience, use this query.

query {
  dataSets {
    nodes {
      consentGroups {
        name
        id
      }
    }
  }
}

{
  "data": {
    "dataSets": {
      "nodes": [
        {
          "consentGroups": [
            {
              "id": "97660d76-02d8-5fd6-0000-11111111aaa11a",
              "name": "Newsletters"
            },
            {
              "id": "97660d76-02d8-5fd6-0000-11111111aaa11a",
              "name": "Promotions"
            },
            {
              "id": "97660d76-02d8-5fd6-0000-11111111aaa11a",
              "name": "Information"
            },
            {
              "id": "97660d76-02d8-5fd6-0000-11111111aaa11a",
              "name": "Custom"
            }
          ]
        }
      ]
    }
  }
}

Approach B: submit consent preferences per channel

In this example, we will add a contact and subscribe them to email and text communications.

mutation createContact {
  createContacts(
    contactsInput: [
      {
        attributes: [
          { name: "Name", value: "Alice" }
          { name: "Last Name", value: "Brown" }
          { name: "Email", value: "[email protected]" }
          { name: "Cell Phone", value: "+14155550132" }
        ]
        consent: {
          channels: [
            { channel: EMAIL, status: OPT_IN_UNVERIFIED }
            { channel: SMS, status: OPT_IN }
          ]
        }
      }
    ]
    dataSetId: "4fe4136f-c007-44a3-b38f-92220xxxxxxxx"
  ) {
    items {
      contactId
    }
  }
}

{
  "data": {
    "createContacts": {
      "items": [
        {
          "contactId": "a364f922-2845-4718-9705-00000000y000"
        }
      ]
    }
  }
}

Arguments

Arguments supported by the createContacts mutation

Argument name	Input field	Values	Required?	Definition
`dataSetId`		ID	Required	The ID of your audience
`contactsInput`	`attributes`	Array	Required	See the input fields
	`consent`	Array	Optional	See the input fields

Fields nested into the attributes field

Field	Values	Required?	Definition
`name`	String (case-sensitive) ⚠️ To check the names of available attributes, use the Get all contact attributes query.	Required	The name of the attribute to populate for the contact
`value`	Depends on the type of attribute	Required	The value of the attribute

There are 2 fields nested into the consent field: channels and consentGroups. They are mutually exclusive and cannot be submitted together for the same contact.

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`	Indicates if the contact has agreed to receive communication through the channel.
`consentGroups`	`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`	Indicates if the contact has agreed to receive communication through the channel.
	`consentGroupId`		String	The ID of the subscription group to add the contact to
	`status`		One of the following values: - `OPT_IN` - `OPT_OUT` - `OPT_IN_UNVERIFIED`	The contact's status within the subscription group (applies to all of its channels)

Fields

Fields returned by the createContacts mutation

Field	Nested field	Required?	Definition
`items`	`contactId`	Required	A unique system identifier that will be generated for the new contact