Deleting campaign contacts

There are two methods for deleting contacts from Zoom Contact Center outbound campaigns:

  • Delete contacts with custom fields - Tag and remove a subset of contacts directly from a campaign contact list using custom fields.
  • Delete contacts with address books - Delete contacts from an address book that is synced to a campaign contact list.

Delete contacts with custom fields

Use custom fields to tag specific contacts in a campaign contact list, then filter and delete them using the Zoom admin portal or API.

Follow these steps:

  1. Create a custom field on the campaign contact list. This field is what you'll use later to identify which contacts to delete.
  2. Add contacts with the custom field set, giving each one a value you can search on later.
  3. Find the contacts you want to remove by filtering by the custom field value.
  4. Delete the contacts from the list.

Step 1: Create a custom field

Create a custom field using the admin portal or API.

  1. Sign into the Zoom admin portal.
  2. In the navigation pane, choose Contact Center Management.
  3. Choose Campaign Management.
  4. Choose Contacts.
  5. Choose Custom fields.
  6. Choose Add custom field, fill out the form making sure to associate it with the contact list, and choose Add.

To create a campaign contact list's custom field using the API, call the create campaign contact list custom field endpoint.

No query parameters are needed for this call, custom fields are available for all contact lists.

Within the payload body, the custom field name must be provided, in addition to the data type (string, integer, etc.).

Send the following request, replacing <contactListId> with your contact list ID.

Example request

curl https://api.zoom.us/v2/contact_center/outbound_campaign/contact_list_custom_fields \
'{
  "custom_field_name": "contact_field_demo",
  "data_type": "string",
  "contact_list_ids": [
    "<contactListId>"
  ],
  "use_as_routing_profile_parameter": true,
  "use_as_external_url_parameter": false
}'

Example response

{
    "custom_field_id": "<customFieldId>",
    "custom_field_name": "contact_field_demo",
    "data_type": "string",
    "contact_list_ids": ["<contactListId>"]
}

Save the custom_field_id from this response for adding contacts in the next step.

Step 2: Add a contact with a custom field to a contact list

Add a contact using the admin portal or API.

  1. Sign into the Zoom admin portal.
  2. In the navigation pane, choose Contact Center Management.
  3. Choose Campaign Management.
  4. Choose Contacts.
  5. Choose the contact list you want to add the contact to.
  6. Choose Add contact, fill out the form making sure to add the custom field and value, and choose Add.

Contacts with custom fields must be added individually using the create a campaign contact list's contact endpoint.

The contact_list_id is a required query parameter and can be retrieved using the list campaign contact lists endpoint.

Using your saved contact_list_id and custom_field_id, add a new contact. The custom_field_id must be included in the request payload to associate the custom field with the contact.

Send the following request, replacing <contactListId> and <customFieldId> with your values.

Example request

curl https://api.zoom.us/v2/contact_center/outbound_campaign/contact_lists/<contactListId>/contacts \
'{
  "contact_display_name": "Display Name",
  "contact_first_name": "First Name",
  "contact_last_name": "Last Name",
  "contact_phones": [
    {
      "contact_phone_number": "+12345551100",
      "contact_phone_type": "Main"
    }
  ],
  "custom_fields": [
    {
      "custom_field_id": "<customFieldId>",
      "custom_field_value": "1234"
    }
  ]
}'

Example response

{
    "contact_id": "<contactId>",
    "contact_display_name": "Display Name",
    "contact_first_name": "First Name",
    "contact_last_name": "Last Name",
    "contact_phones": [
        {
            "contact_phone_number": "+12345551100",
            "contact_phone_type": "Main"
        }
    ],
    "custom_fields": [
        {
            "custom_field_id": "<customFieldId>",
            "custom_field_value": "1234"
        }
    ]
}

Save the custom_field_value you assigned for filtering contacts in the next step.

Step 3: Find contacts by custom field value

Filter contacts by custom field value to identify which ones to delete.

Note

Filtering contacts by custom field value is not supported in the admin portal.

To find contacts tagged with a specific custom field value, call the list campaign contact list's contacts endpoint and filter by the custom field.

The contact_list_id is a required query parameter. Use the custom_field_id and custom_field_value query parameters to filter results to only contacts matching that custom field value.

Send the following request, replacing <contactListId>, <customFieldId>, and <customFieldValue> with your values.

Example request

curl https://api.zoom.us/v2/contact_center/outbound_campaign/contact_lists/<contactListId>/contacts?custom_field_id=<customFieldId>&custom_field_value=<customFieldValue>

Example response

{
    "contacts": [
        {
            "contact_id": "<contactId>",
            "contact_display_name": "Display Name",
            "contact_first_name": "First Name",
            "contact_last_name": "Last Name",
            "contact_phones": [
                {
                    "contact_phone_number": "+12345551100",
                    "contact_phone_type": "Main"
                }
            ],
            "custom_fields": [
                {
                    "custom_field_id": "<customFieldId>",
                    "custom_field_value": "<customFieldValue>"
                }
            ]
        }
    ]
}

Save the contact_id values from this response for deletion in the next step.

Step 4: Delete a campaign contact list contact

Delete the contacts from the campaign contact list using the admin portal or API.

To delete contacts in the admin portal, use the contact_display_name values from the previous step to locate and delete them manually.

To delete contacts from a campaign contact list, call the remove campaign contact list's contact endpoint. This endpoint requires both the contact_list_id and the contact_id as query parameters.

A contact's contact_id can be retrieved from the list campaign contact list's contacts endpoint, or from the return body of a successful contact creation call.

Send the following request, replacing <contactListId> and <contactId> with your values.

Example request

curl -X DELETE https://api.zoom.us/v2/contact_center/outbound_campaign/contact_lists/<contactListId>/contacts/<contactId>

Example response

204 No Content

You can verify deletion by checking the admin portal or by making another call to the list campaign contact list's contacts endpoint.

Delete contacts with address books

Delete contacts from an address book individually or in bulk using the API. If the address book is synced to a campaign contact list, deletions propagate automatically.

Follow these steps:

  1. Get your address book ID.
  2. Delete the contacts individually or in bulk.
  3. Verify the deletion propagates to any synced campaign contact lists.

Step 1: Get the address book ID

To find the address book ID, first call the List address book units endpoint to get your unit IDs.

Example request

curl https://api.zoom.us/v2/contact_center/address_books/units

Example response

{
    "units": [
        {
            "unit_id": "abc123xyz",
            "unit_name": "Customer Service"
        }
    ]
}

Then call the List address books endpoint with a unit ID to retrieve the address books and their IDs.

Send the following request, replacing <unitId> with your unit ID from the previous response.

Example request

curl https://api.zoom.us/v2/contact_center/address_books?unit_id=<unitId>

Example response

{
    "address_books": [
        {
            "address_book_id": "def456uvw",
            "address_book_name": "VIP Customers"
        }
    ]
}

Save the address_book_id for use in the following steps.

Note

You can also find the address book ID in the admin portal by opening the browser console's Network tab (right-click, choose Inspect, then choose Network), selecting an address book, and viewing the address book ID in the last loaded request URL.

Step 2: Delete an address book contact

To delete an address book contact, you'll need both the address book ID and the ID of the contact you wish to remove.

To find the contact_id, call the List address book contacts endpoint. The address_book_id is a required query parameter.

Send the following request, replacing <addressBookId> with your address book ID.

Example request

curl https://api.zoom.us/v2/contact_center/address_books/<addressBookId>/contacts

Example response

{
    "contacts": [
        {
            "contact_id": "zeYjXoDOS_eV1QmTpj63PQ",
            "display_name": "Jill Chill",
            "first_name": "Jill",
            "last_name": "Chill",
            "phones": [
                {
                    "phone_number": "+12048002447",
                    "phone_type": "main"
                }
            ],
            "emails": ["user@example.com"],
            "consumer_ids": ["cvC2JxWkToWZsJUenBvNnw"],
            "custom_fields_url": "https://api.zoom.us/v2/contact_center/address_books/custom_fields/contacts/zeYjXoDOS_eV1QmTpj63PQ"
        }
    ]
}

Once you have the contact_id, pass it to the Delete an address book contact endpoint. This endpoint requires both the address_book_id and contact_id as query parameters.

Send the following request, replacing <addressBookId> and <contactId> with your values.

Example request

curl -X DELETE https://api.zoom.us/v2/contact_center/address_books/<addressBookId>/contacts/<contactId>

Example response

204 No Content

Batch delete address book contacts

To delete multiple contacts at once, use the Batch delete address book contacts endpoint. This endpoint requires the address_book_id as a query parameter and the contact IDs in the request body.

Send the following request, replacing <addressBookId> with your address book ID and the contact IDs with your values.

Example request

curl -X DELETE https://api.zoom.us/v2/contact_center/address_books/<addressBookId>/contacts/batch \
'{
  "contact_ids": [
    "<contactId1>",
    "<contactId2>",
    "<contactId3>"
  ]
}'

Example response

204 No Content

Step 3: Sync with campaign contact list

If your address book is synced with a campaign contact list, deletions propagate automatically. You can verify by calling the list campaign contact list's contacts endpoint to confirm the contact is no longer in the list.