searchContacts

Returns the Contacts in the List that match the search criteria.

searchContacts

Returns the Contacts in the List that match the search criteria.

Top ↑

Syntax

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

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.

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 Contacts in the List 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.
returned_fields (array - optional)

An array containing the names of the Fields to return in the result. Field names are case sensitive. Valid values are:

  • all - Return all Contact Fields and all system values (default).
  • The name of any Field in the List.
  • Any of the available system values. See the remarks section below.

Return Value

Returns an array containing zero or more associative arrays of Contact details with the Fields specified in return_fields. See the remarks section below for the list of values this method returns.

Examples

The following code samples cover three uses of the searchContacts method: accessing all Contacts in a List, finding Contacts added within a certain date range, and finding all Contacts within a specific demographic.

In the first example, searchContacts passes the list_id, 1234567, but does not send any search criteria. Without search criteria, searchContacts() returns all of the Contacts in the List.

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

$returned_fields = array('id', 'Email');

$api = new Api($url, 'YOURAPIKEY');
$contacts = $api->invokeMethod('searchContacts', $list_id, array(), 0, 0, '', '', $returned_fields);

// loop over result
foreach ($contacts as $contact_details) {
    print "Found Contact ". $contact_details['id'] ." with email ". $contact_details['Email'] ."\n";
}
{
    "id": 1,
    "method": "searchContacts",
    "params": [
        "YOURAPIKEY",
        1234567,
        [],
        0,
        0,
        "",
        "",
        [
            "id",
            "Email"
        ]
    ]
}
{
    "id": 1,
    "result": [
        {
            "id": "1",
            "Email": "jdoe@example.com"
        },
        {
            "id": "2",
            "Email": "jblogs@example.com"
        },
        {
            "id": "4",
            "Email": "test@example.com"
        },
        {
            "id": "5",
            "Email": "user@example.com"
        },
        {
            "id": "6",
            "Email": "admin@example.com"
        },
        {
            "id": "7",
            "Email": "contact@example.com"
        }
    ],
    "error": null
}

In the second example, searchContacts() sends the list_id, and a search criteria array. The search criteria find all Contacts who were added to the List between June 1, 2012 and June 15, 2012.

// search criteria is AND'ed by default
// creation_time is a unix timestamp
$search_criteria = array(
    array('creation_time', 'greater_than', strtotime('2012-06-01')),
    array('creation_time', 'less_than', strtotime('2012-06-15')),
);

$contacts = $api->invokeMethod('searchContacts', $list_id, $search_criteria);
{
    "id": 1,
    "method": "searchContacts",
    "params": [
        "YOURAPIKEY",
        1234567,
        [
            [
                "creation_time",
                "greater_than",
                1338472800
            ],
            [
                "creation_time",
                "less_than",
                1339682400
            ]
        ]
    ]
}
{
    "id": 1,
    "result": [
        {
            "Email": "jdoe@example.com",
            "First Name": "John",
            "Date of Birth": "1979-05-16",
            "id": "1",
            "creation_time": "1349409860",
            "webform_id": 0,
            "last_modified_time": "1349409860",
            "subscribed_via": "bulk_upload",
            "is_unsubscribed": 0,
            "is_bounce_deactivated": 0,
            "last_message_time": 1359085024,
            "double_opt_in": "0",
            "double_opt_in_time": "0",
            "is_active": "1"
        },
        {
            "Email": "admin@example.com",
            "Mobile Phone": "",
            "First Name": "Administrator",
            "Date of Birth": "1988-11-06",
            "id": "6",
            "creation_time": "1350365894",
            "webform_id": 0,
            "last_modified_time": "1350365894",
            "subscribed_via": "single_addition",
            "is_unsubscribed": 0,
            "is_bounce_deactivated": 0,
            "last_message_time": 0,
            "double_opt_in": "0",
            "double_opt_in_time": "0",
            "is_active": "1"
        }
    ],
    "error": null
}

In the third example, searchContacts() sends the list_id and a search criteria array. In this case, the array specifies all Contacts in the List born after December 31, 1979.

// assuming there is a 'Date of Birth' field in the list:
$search_criteria = array(
    array('Date of Birth', 'greater_than', '1979-12-31'),
);

$contacts = $api->invokeMethod('searchContacts', $list_id, $search_criteria);
{
    "id": 1,
    "method": "searchContacts",
    "params": [
        "YOURAPIKEY",
        1234567,
        [
            [
                "Date of Birth",
                "greater_than",
                "1979-12-31"
            ]
        ]
    ]
}
{
    "id": 1,
    "result": [
        {
            "Email": "admin@example.com",
            "Mobile Phone": "",
            "First Name": "Administrator",
            "Date of Birth": "1988-11-06",
            "id": "6",
            "creation_time": "1350365894",
            "webform_id": 0,
            "last_modified_time": "1350365894",
            "subscribed_via": "single_addition",
            "is_unsubscribed": 0,
            "is_bounce_deactivated": 0,
            "last_message_time": 0,
            "double_opt_in": "0",
            "double_opt_in_time": "0",
            "is_active": "1"
        }
    ],
    "error": null
}

Remarks

The following table shows the system values that are returned in addition to the List Fields.

Key Type Searchable Description
id int Yes The id of the Contact.
creation_time int Yes Timestamp of when the Contact was created.
double_opt_in bool Yes Value indicating whether the Contact has confirmed their subscription.
double_opt_in_time int Yes Timestamp of when the Contact confirmed their subscription.
is_active bool Yes Value indicating whether the Contact is active.
is_bounce_deactivated bool Yes Value indicating whether the Contact was automatically deactivated due to receiving too many bounces.
is_unsubscribed bool Yes Value indicating whether the Contact is unsubscribed from the List.
last_click_time int Yes Timestamp of the last time the Contact clicked a link in a message.
last_modified_time int Yes Timestamp of when the Contact was last modified.
last_message_time int Yes Timestamp of the last time a message was sent to the Contact.
last_open_time int Yes Timestamp of the last time the Contact opened a message.
subscribed_via string Yes How the Contact subscribed. Valid values are web_form, bulk_upload, single_addition, api, quick_send, inbound_message or other.
webform_id int Yes The ID of the Web Form the Contact used to subscribe.

Note that returning all Fields requires the system to transfer a large amount of data and uses a significant amount of your system's resources. Therefore, use the returned_fields parameter to specify the Fields actually needed in the result.

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
311 Invalid Search Parameter Format search_critera is not valid

See Also

Method References
Popular Pages