Delete contacts

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.

FieldValuesRequired?Definition
addressableListArray 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).
deleteReasonEnum. Valid values:

- USER_REQUEST
- DEPROVISIONING
- RIGHT_TO_BE_FORGOTTEN
RequiredThe reason why the contacts are being deleted.

⚠️ There can be only one reason per mutation.
keyListArray 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:

FieldValuesRequired?Definition
fieldStringRequiredThe name of the addressable attribute to use for identification
eqStringRequiredThe value of the addressable attribute for the contact

Fields

Fields returned by the deleteContacts mutation

FieldValuesRequired?Definition
deletedCountIntegerRequiredThe number of contacts deleted

Possible error messages

Error codeDefinition
CONTACT_ADDRESSABLE_NOT_ALLOWED_WHEN_CONTACT_KEY_DEFINEDYour 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_FAILEDThe contact hasn't been deleted due to an error. Try resubmitting your request.