searchLists

Returns the Lists that match the search criteria.

searchLists

Returns the Lists that match the search criteria.

Top ↑

Syntax

object searchLists(
    string api_key,
  [ 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.

search_criteria (array - optional)

An array of search criteria. See the remarks section below for the list of values which are searchable.
If you do not specify search criteria, all Lists are returned.

limit (int - optional)

Maximum number of items to return.

offset (int - optional)

Number of items to skip before beginning to return results. See Using Search Methods for information about using the offset parameter with the limit parameter to include pagination in your results.

sort_by (string - optional)

The name of the value to sort the results by.

sort_order (string - optional)

The order the results are returned 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 object containing zero or more objects of List details. See the remarks section below for the list of values this method returns.

Examples

Retrieve all Lists in the Prospects Folder, ordered by name.

$search_criteria = array(
    array('folder_name', 'exactly', 'Prospects')
);

$api = new Api($url, 'YOURAPIKEY');
$lists = $api->invokeMethod('searchLists', $search_criteria, 0, 0, 'name', 'ASC');

  // loop over result
foreach ($lists as $list_details) {
    print "Found ". $list_details['name'] ."\n";
}
{
    "id": 1,
    "method": "searchLists",
    "params": [
        "YOURAPIKEY",
        [
            ["folder_name", "exactly", "Prospects"]
        ],
        0,
        0,
        "name",
        "ASC"
    ]
}
{
    "id": 1,
    "result": [
        {
            "id": 1234567,
            "creator_user_id": 23456,
            "name": "Example List",
            "creation_time": 1323139542,
            "last_modified_time": 1323139542,
            "on_register_address": "alice@example.com,bob@example.com",
            "on_update_address": "",
            "on_unsubscribe_address": "",
            "disallow_duplicate_contacts": false,
            "folder_id": 34567,
            "contact_count": 8,
            "country_code": 61,
            "virtual_number": 0,
            "sms_stop_words": "REMOVE ME,UNSUBSCRIBE",
            "sms_response_action": "do_nothing",
            "sms_response_field_ids": "",
            "folder_name": "Prospects",
            "address_types": "email,mobile",
            "creator_name": "Bob Smith",
            "allow_send_to_duplicates": false
        }
    ],
    "error":null
}

Remarks

The following table shows the values that are returned.

Key Type Searchable Description
id int Yes List ID.
name string Yes The name of the List.
allow_send_to_duplicates bool Yes When set to true, allows message to be sent to duplicate Contacts (Contacts with the same address).
contact_count int Yes The number of Contacts in the List.
country_code int Yes The default country dialling prefix used for Contacts in the List.
creation_time int Yes Timestamp indicating when the List was created.
creator_name string Yes The name of the User who created the List.
creator_user_id int Yes The User who created the List.
disallow_duplicate_contacts bool Yes When set to true, duplicate Email addresses cannot be added.
folder_id int Yes The ID of the Folder containing the List.
folder_name string Yes The name of the Folder containing the List.
last_modified_time int Yes Timestamp indicating when the List was last modified.
on_register_address string Yes A comma separated list of addresses that receive a Notifications when a Contact subscribes to the List.
on_unsubscribe_address string Yes A comma separated list of addresses that receive a Notifications when a Contact unsubscribes from the List.
on_update_address string Yes A comma separated list of addresses that receive a Notifications when a Contact updates their profile.
sms_stop_words string Yes A comma separated list of SMS stop words that Contacts can reply with to unsubscribe.
sms_response_action string Yes The action to perform when an SMS response is received. Valid values are do_nothing, add_new_contact or update_contact.
sms_response_field_ids string Yes A comma separated list of Field ID's where Contact SMS responses are saved.
virtual_number string Yes The virtual number used when Contacts subscribe to the List via SMS. Also the number the system uses when sending SMS messages.
address_types string No A comma separated list of address Field types in the List. Valid values are email or mobile.

Error Codes

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

Code Error Description
311 Invalid Search Parameter Format search_critera is not valid

See Also