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