BrandMail API - searchUsers

Syntax

array searchUsers(
    string api_key,
  [ int account_id,
    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.

account_id (int - optional)

ID of the Account to search for Users. The default value is the Account Id of the current User.
Note: This parameter is required if the API User is not an Account owner.

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 Users in the Account 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 array containing zero or more associative arrays of User details. See the remarks section below for the list of values this method returns.

Examples

$api = new Api($url, 'YOURAPIKEY');

$search_criteria = array(

    array('email', 'contains', 'gmail'),

    array('username', 'contains', 'tom')

);

$account_users = $api->invokeMethod('searchUsers', 123456, $search_criteria);

{

    "id": 1,

    "method": "searchContacts",

    "params": [

        "YOURAPIKEY",

        123456,

        [

            [

                "email",

                "contains",

                "gmail"

            ],

            [

                "username",

                "contains",

                "tom"

            ]

        ],

    ]

}

{

    "id": 1,

    "result": [

        {

            "id": "6789012",

            "account_id": "123456",

            "username": "tom",

            "first_name": "Edited",

            "last_name": "Last Name",

            "email": "example@example.com",

            "phone": "56565656",

            "mobile": "0412312312",

            "fax": "57575757",

            "position": "Manager",

            "has_accepted_terms": "0",

            "creation_time": "1361944217",

            "last_login_time": "0",

            "login_count": "0",

            "is_read_only": "1",

            "timezone": "Australia\/Brisbane",

            "name": "Edited Last Name",

            "receives_promotional": "1"

        }

    ],

    "error": null

}

Remarks

The following table shows the values that are returned.

Key	Type	Searchable	Description
`id`	int	Yes	User ID.
`account_id`	int	No	Account ID.
`username`	string	Yes	Username.
`name`	string	Yes	User's full name.
`first_name`	string	Yes	First name.
`last_name`	string	Yes	Last Name.
`email`	string	Yes	Email address.
`phone`	string	Yes	Phone number.
`mobile`	string	Yes	Mobile number.
`fax`	string	Yes	Fax number.
`position`	string	Yes	Title of the User's position.
`timezone`	string	Yes	User's timezone in tz database format (area/location). For example, Australia/Brisbane. See getTimezoneList.
`creation_time`	int	Yes	Timestamp indicating when the Account was created.
`last_login_time`	int	Yes	Timestamp indicating when the User last logged in.
`login_count`	int	Yes	Number of times the User has logged in.
`has_accepted_terms`	bool	Yes	Whether the User has accepted Terms and Conditions.
`receives_promotional`	bool	Yes	Whether the User has opted to receive promotional messages.
`is_read_only`	bool	Yes	Value indicating if the User is able to modify the Account.

Error Codes

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

Code	Error	Description
`310`	A valid 'account_id' must be provided unless logged in as an Account owner	The `account_id` parameter was omitted and the user logged in to the API is not an Account owner
`321`	Administrative access denied	`account_id` is not a sub-Account or the owner of the Account
`328`	Unable to load Account	`account_id` is not a valid Account
`328`	Unable to load Account: Account has been deleted	`account_id` is a deleted Account
`311`	Invalid Search Parameter Format	`search_criteria` is not valid

searchUsers