---
updatedAt: 2026-09-04T15:04:52.000Z
---

# Update consent statuses for contacts

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.

```graphql Mutation
mutation ($key: String!, $consent: ConsentInput!) {
  updateContacts(
    updateContactInputs: [{ key: $key, to: { consent: $consent } }]
  ) {
    modifiedCount
  }
}
```
```json Response
{
  "data": {
    "updateContacts": {
      "modifiedCount": 1
    }
  }
}
```

# 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`).

```graphql Mutation
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
  }
}
```
```json Response
{
  "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.

```graphql Mutation
mutation {
  updateContacts(
    updateContactInputs: [
      {
        key: "DDJ_98716421"
        to: {
          attributes: [
            { name: "Email Address", value: "mario@example.com" }
          ]
          consent: { channels: { channel: EMAIL, status: OPT_IN } }
        }
      }
      {
        key: "DEW_98716421"
        to: {
          consent: { channels: { channel: SMS, status: OPT_OUT } }
        }
      }
    ]
  ) {
    modifiedCount
  }
}
```
```json Response
{
  "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).

```graphql Mutation
mutation {
  updateContacts(
    updateContactInputs: [
      {
        addressable: [{ field: "Email", eq: "taio@example.com" }]
        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
  }
}
```
```json Response
{
  "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.

<Table align={["left","left","left","left"]}>
  <thead>
    <tr>
      <th>
        Field
      </th>

      <th>
        Values
      </th>

      <th>
        Values
      </th>

      <th>
        Definition
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `addressable`
      </td>

      <td>
        Array of objects
      </td>

      <td>
        Optional
      </td>

      <td>
        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).

        :warning: Do not use this field together with `key`.
      </td>
    </tr>

    <tr>
      <td>
        `key`
      </td>

      <td>
        String
      </td>

      <td>
        Optional
      </td>

      <td>
        The contact key assigned to the contact.

        :warning: Do not use this field together with `addressable`.
      </td>
    </tr>

    <tr>
      <td>
        `to`
      </td>

      <td>
        Array of objects
      </td>

      <td>
        Required
      </td>

      <td>
        Add an object for each contact attribute you want to update.
      </td>
    </tr>
  </tbody>
</Table>

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:

<Table align={["left","left","left","left"]}>
  <thead>
    <tr>
      <th>
        Field
      </th>

      <th>
        Nested field
      </th>

      <th>
        Values
      </th>

      <th>
        Definition
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `attributes`
      </td>

      <td>
        `name`
      </td>

      <td>
        String
      </td>

      <td>
        The name of the contact attribute you want to update
      </td>
    </tr>

    <tr>
      <td>

      </td>

      <td>
        `value`
      </td>

      <td>
        Depends on the type of contact attribute.
      </td>

      <td>
        The new value of the contact attribute
      </td>
    </tr>

    <tr>
      <td>
        `consent`
      </td>

      <td>
        `channels`
      </td>

      <td>
        Array of objects
      </td>

      <td>
        Use this field if your marketing team manages consent by the channel.

        Each channel requires its own object.
      </td>
    </tr>

    <tr>
      <td>

      </td>

      <td>
        `consentGroups`
      </td>

      <td>
        Array of objects
      </td>

      <td>
        Use this field if your marketing team manages consent on the consent group basis.

        Each consent group requires its own object.
      </td>
    </tr>
  </tbody>
</Table>

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

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Field
      </th>

      <th>
        Values
      </th>

      <th>
        Definition
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `channel`
      </td>

      <td>
        Enumeration. Valid values:

        \- `EMAIL`<br />- `SMS`<br />- `WHATSAPP`<br />- `MOBILE`
      </td>

      <td>
        The type of communication channel
      </td>
    </tr>

    <tr>
      <td>
        `status`
      </td>

      <td>
        Enumeration. Valid values:

        \- `OPT_IN`<br />- `OPT_OUT`<br />- `OPT_IN_UNVERIFIED`
      </td>

      <td>
        Indicates if the contact has agreed to receive communication through the channel.
      </td>
    </tr>
  </tbody>
</Table>

Fields supported by objects within the `consentGroups` field

<Table align={["left","left","left","left"]}>
  <thead>
    <tr>
      <th>
        Field
      </th>

      <th>
        Nested field
      </th>

      <th>
        Values
      </th>

      <th>
        Definition
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `channels`
      </td>

      <td>
        `channel`
      </td>

      <td>
        Enumeration. Valid values:

        \- `EMAIL`<br />- `SMS`<br />- `WHATSAPP`<br />- `MOBILE`
      </td>

      <td>
        A communication channel associated with the consent group.

        :warning: Don't use the `channels` field together with `status`.
      </td>
    </tr>

    <tr>
      <td>

      </td>

      <td>
        `status`
      </td>

      <td>
        Enumeration. Valid values:

        \- `OPT_IN`<br />- `OPT_OUT`<br />- `OPT_IN_UNVERIFIED`
      </td>

      <td>
        The contact's consent status in relation to the communication channel
      </td>
    </tr>

    <tr>
      <td>
        `consentGroupId`
      </td>

      <td>

      </td>

      <td>
        String
      </td>

      <td>
        The ID of the consent group the contact has been added to
      </td>
    </tr>

    <tr>
      <td>
        `status`
      </td>

      <td>

      </td>

      <td>
        Enumeration. Valid values:

        \- `OPT_IN`<br />- `OPT_OUT`<br />- `OPT_IN_UNVERIFIED`
      </td>

      <td>
        The contact's status within the consent group (applies to all of its channels).

        :warning: Don't use this field together with `channels`.
      </td>
    </tr>
  </tbody>
</Table>

# 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

This operation can return several error codes. For the full list, with definitions and the operations each code applies to, see <Anchor target="_blank" href="https://developer.goacoustic.com/acoustic-connect/reference/error-codes">Error codes</Anchor>.

<br />