searchFolders

Returns the Folders that match the search criteria.

searchFolders

Returns the Folders that match the search criteria.

Top ↑

Syntax

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

folder_type (string)

The type of Folders to search for. Valid values are: list, message or file.

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 Folders with the specified folder_type 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 Folder details. See the remarks section below for the list of values this method returns.

Examples

This example finds the "Competition" Folder.

$folder_search = array(
    array('name', 'exactly', 'Competition')
);

// API Call
$api = new Api($url, 'YOURAPIKEY');
$folder_details = $api->invokeMethod('searchFolders', 'list', $folder_search);
{
    "id": 1,
    "method": "searchFolders",
    "params": [
        "YOURAPIKEY",
        "list",
        [
            ["name", "exactly", "Competition"],
        ],
    ]
}
{
    "id": 1,
    "result": [
        {
            "id": 123456,
            "name": "Competition",
            "creation_time": 1362102490,
            "type": "list",
            "item_count": 0
        }
    ],
    "error": null
}

Remarks

The following table shows the values that are returned.

Key Type Searchable Description
id int Yes Folder id.
name string Yes The name of the Folder.
creation_time int Yes Timestamp indicating when the Folder was created.
item_count int Yes The number of items in the Folder.
type string No The Folder type. Valid values are: list, message or file.

Error Codes

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

Code Error Description
311 Invalid Search Parameter Format search_criteria is not valid.
302 Invalid Folder Type folder_type is invalid. Must be list, message, or file.

See Also