To delete contacts from the audience, use the deleteContacts mutation. This operation is permanent and irreversible. All data associated with the contacts will be deleted.

Ways to identify contacts

When you run the deleteContacts mutation, use contact keys to identify the contacts you want to delete. Here is an example.

mutation deleteContacts {
  deleteContacts(
    where: {
      keyList: ["PISCX-098724242434", "PISCX-098724242433", "PISCX-0987240000220"]
      deleteReason: USER_REQUEST
    }
  ) {
    deletedCount
  }
}

{
  "data": {
    "deleteContacts": {
      "deletedCount": 3
    }
  }
}

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

mutation deleteContacts {
  deleteContacts(
    where: {
      addressableList: [
        { field: "Email Address", eq: "[email protected]" }
        { field: "Email Address", eq: "[email protected]" }
      ]
      deleteReason: USER_REQUEST
    }
  ) {
    deletedCount
  }
}

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

Running the mutation

If you haven't used our API before, see Using the Connect API for instructions. It explains how to authenticate your calls and suggests some tools for testing.

Mutation structure

Arguments

The deleteContacts mutation contains the where argument at the top level. It's an object. Here are the input fields it supports.

Field	Values	Required?	Definition
`addressableList`	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).
`deleteReason`	Enum. Valid values: - `USER_REQUEST` - `DEPROVISIONING` - `RIGHT_TO_BE_FORGOTTEN`	Required	The reason why the contacts are being deleted. ⚠️ There can be only one reason per mutation.
`keyList`	Array of strings	Optional	The contact keys assigned to the contacts you want to delete. ⚠️ Do not use this field together with `addressableList`.

Fields nested into the addressableList field:

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

Fields

Fields returned by the deleteContacts mutation

Field	Values	Required?	Definition
`deletedCount`	Integer	Required	The number of contacts deleted

Possible error messages

Error code	Definition
CONTACT_ADDRESSABLE_NOT_ALLOWED_WHEN_CONTACT_KEY_DEFINED	Your audience has the Contact key attribute defined. You must use contact keys for identification. If you have a contact without a contact key, the only way to delete it is through the Connect application.
CONTACT_DELETE_FAILED	The contact hasn't been deleted due to an error. Try resubmitting your request.