To delete contacts from the audience, use the deleteContacts mutation.

Typical use cases:

• Remove contacts who request deletion under data privacy regulations (GDPR, CCPA).
• Clean up duplicate or test contacts from your audience.
• Delete inactive contacts as part of data retention policies.

🚧

Warning

This operation permanently removes all contact data including attribute values and consent preferences. Make sure you have the legal basis and proper authorization before deleting contacts.

Ways to identify contacts

When you run the deleteContacts mutation, you need to identify which contacts to delete. You can use either contact keys or addressable attributes (email and phone number) depending on your audience configuration.

Identifying contacts with contact keys

If your audience uses contact keys, use the keyList field to identify contacts.

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

{
  "data": {
    "deleteContacts": {
      "deletedCount": 1
    }
  }
}

Example: A customer exercises their right to be forgotten under GDPR. Using their account ID (stored as the contact key), the compliance team deletes their contact record, ensuring all personal data is removed from the marketing database.

Identifying contacts with addressable attributes

If your audience doesn't have the contact key attribute defined, you must rely on addressable attributes (email or phone number) for identification.

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

{
  "data": {
    "deleteContacts": {
      "deletedCount": 1
    }
  }
}

Example: A subscriber requests removal from all marketing lists. Using their email address, the marketing team deletes the contact record, honoring the unsubscribe request and maintaining compliance with anti-spam regulations.

Using two addressable attributes

If there is a chance that multiple contacts share the same email address or phone number in your audience, you can use a combination of both to uniquely identify a contact.

mutation deleteContacts {
  deleteContacts(
    where: {
      addressableList: [
        { field: "Email Address", eq: "[email protected]" }
        { field: "Phone Number", eq: "+7123905600" }
      ]
      deleteReason: DEPROVISIONING
    }
  ) {
    deletedCount
  }
}

{
  "data": {
    "deleteContacts": {
      "deletedCount": 1
    }
  }
}

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 arguments

• where (required): Object - Contains the identification method and deletion reason.

Where object

• addressableList: Array of objects - You must add this field to the mutation if your audience doesn't have the contact key attribute. Each contact requires a separate object. Important: Do not use this field together with keyList.
• deleteReason (required): Enum - The reason why the contacts are being deleted. Valid values: USER_REQUEST, DEPROVISIONING, RIGHT_TO_BE_FORGOTTEN. Note: There can be only one reason per mutation.
• keyList: Array of strings - The contact keys assigned to the contacts you want to delete. Important: Do not use this field together with addressableList.

Addressable list object

Used within the addressableList array to identify contacts by email or phone number.

Both fields are required:

• eq (required): String - The value of the addressable attribute for the contact.
• field (required): String - The name of the addressable attribute to use for identification.

Response fields

The mutation returns a JSON response containing:

• data (required): Object - Root response object.
  • deleteContacts (required): Object - Type of operation performed.
    • deletedCount (required): Integer - The number of contacts deleted.

Possible error messages