deleteContacts

Deletes one or more Contacts from a List.

deleteContacts

Deletes one or more Contacts from a List.

Top ↑

Syntax

array deleteContacts(
    string api_key,
    int list_id,
    array contact_ids,
  [ array search_criteria,
    int limit,
    int offset,
    string sort_by,
    string sort_order ] 
);

Parameters

api_key (string)

The key required to access the API. See Getting Started for more information.

list_id (int)

The ID of the List containing the Contacts to delete.

contact_ids (array)

An array of Contact ID's to delete. This parameter is ignored if the search_criteria parameter is used.

search_criteria (array - optional)

An array of search criteria that selects the Contacts to be deleted. Set contact_ids to an empty array when using search criteria to delete Contacts. See searchContacts for a description of the values that can be searched on.

limit (int - optional)

Maximum number of Contacts to delete.

offset (int - optional)

Number of Contacts to skip before beginning to delete Contacts.

sort_by (string - optional)

The name of the value to sort the Contacts by.

sort_order (string - optional)

The order to sort the Contacts in (either ascending or descending). The default is descending. Valid values are:

  • DESC - Sort from highest to lowest (default).
  • ASC - Sort from lowest to highest.

Return Value

Returns an associative array of boolean values indexed by Contact ID, indicating the Contacts that were successfully deleted.

Examples

In this example, deleteContacts deletes Contacts 1, 2 and 3 from List 1234567.

$list_id = 1234567; // can be obtained using searchLists()

$contact_ids = array(1, 2, 3);

$api = new Api($url, 'YOURAPIKEY');
$deleted_contacts = $api->invokeMethod('deleteContacts', $list_id, $contact_ids);

// loop over the result
foreach ($deleted_contacts as $deleted_contact_id => $success) {
    if ($success) {
        print "Contact ".$deleted_contact_id." deleted successfully\n";
    }
}
{
    "id": 1,
    "method": "deleteContacts",
    "params": [
        "YOURAPIKEY",
        1234567,
        [1, 2, 3]
    ]
}
{
    "id": 1,
    "result": {
        "1": true,
        "2": true,
        "3": true
    },
    "error": null
}

In this example, deleteContacts() deletes all Contacts with the email alice@example.com.

$search_criteria = array(
    array('Email', 'exactly', 'alice@example.com')
);

$deleted_contacts = $api->invokeMethod('deleteContacts', $list_id, array(), $search_criteria);
{
    "id": 1,
    "method": "deleteContacts",
    "params": [
        "YOURAPIKEY",
        1234567,
        [],
        [
            ["Email", "exactly", "alice@example.com"]
        ]
    ]
}
{
    "id": 1,
    "result": {
        "18": true,
        "26": true
    },
    "error": null
}

Remarks

If you delete a Contact from a List, and it has previously been added to the Unsubscriber List, it remains on the Unsubscriber List. Therefore, if you attempt to upload the Contact in the future and indicate that Contacts unsubscribed from any List should not be uploaded, the Contact will not be uploaded.

Use the clearList method to delete all Contacts from the List.

Error Codes

This method may return the following error codes in addition to the standard error codes:

Code Error Description
303 Unable to Load List list_id is not a valid List
313 Cannot Edit Account Lists list_id is an Account List. Contacts in the Account List cannot be deleted.

See Also