To delete contacts from the audience, use the deleteContacts mutation. It lets you delete up to 25 contacts at a time.

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.

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.

Matching on multiple attributes together

If there is a chance that multiple contacts share the same email address or phone number, you can combine both into a single match. Each inner list is matched independently. Selectors inside the same inner list must all match the same contact.

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

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

updateContacts.addressable uses a flat array ([ContactAddressableSelector!]), unlike deleteContacts.addressableList, which nests one level deeper. The two shapes represent the same concept but are not interchangeable — check which mutation you're using before reusing an example.

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 arrays - You must add this field to the mutation if your audience doesn't have the contact key attribute. Each contact requires a separate inner list. 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, IDENTITY_MERGE 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

This operation can return several error codes. For the full list, with definitions and the operations each code applies to, see Error codes.