Retrieve()
Retrieve an array of folders that meet the criteria that you specify.
| Ordinal | Type | Description |
|---|---|---|
1 | JSON object | Required. A JSON object that contains search criteria. |
A simple search contains a single criterion. To perform a simple search, pass a JSON object that contains a Property, a SimpleOperator, and a Value. In some cases, such as when you search for a null value, you can omit the Value.
For example, a simple search can return all folders with an ID between 123456 and 234567, as shown in this code sample.
A complex search contains two criteria that are connected with AND or OR logic. To perform a complex search, pass a JSON object that contains a LeftOperand object, a LogicalOperator, and a RightOperand object.
Both the LeftOperand and RightOperand objects contain the same content as a simple query. That is, they both contain a Property, a SimpleOperator, and a Value.
The value of LogicalOperator is either AND or OR, depending on the type of logic that you want to use to connect the two operands.
This sample shows a complex search that returns image folders where the name of the folder contains the phrase "LoyaltyRewards."
The Property contains the name of the field to perform the search in. For example, to search for folders based on their name, specify Name. This table lists several common properties.
| Property | Type | Description |
|---|---|---|
Name | String | The name of the folder. |
ID | Number | The unique ID of the folder. |
Description | String | The optional description of the folder. |
ContentType | String | The type of content that the folder contains. For a list of possible values, see Value. |
IsEditable | Boolean | Indicates whether the folder can be edited. |
PartnerKey | String | An identifier for the folder that can be used by external partners. |
ObjectID | String | A unique ID for the folder. |
CustomerKey | String | An external identifier for the folder. |
You can also use dot notation to specify fields in child objects. For example, to search based on the name of the parent folder, specify ParentFolder.Name.
For the SimpleOperator property, specify the comparison that you want to perform between the Property and the Value. This table lists the comparisons that you can perform.
| Operator | Description |
|---|---|
between | Search for a value that’s between two specified values. For example, ID BETWEEN ["123456","987654"] searches for all ID values greater than or equal to 123456 and less than or equal to 987654. |
equals | Search for an exact match. |
greaterThan | Search for a numeric value that’s greater than the specified value. |
greaterThanOrEqual | Search for a numeric value that’s greater than or equal to the specified value. |
in | Search for any of the values in a list that contains multiple values. For example ID IN {"123456","234567","345678"} searches for any ID values that are exactly 123456, 234567, or 345678. |
isNotNull | Search for any non-null value. |
isNull | Search for null values. |
lessThan | Search for a numeric value that’s less than the specified value. |
lessThanOrEqual | Search for a numeric value that’s less than or equal to the specified value. |
like | Search for a string that matches a specified pattern. This operator supports all Transact-SQL wildcard operators. |
notEquals | Search for any value that doesn’t exactly match the specified value. |
For the Value property, specify the value that you want to search for.
If you specify contentType for the Property value, specify the type of folder you want to return. This table lists the possible values for this property.
| ContentType | Description |
|---|---|
abtest | A/B Test folder |
asset | Content asset folder |
automated_email | Automated email folder |
automations | Automation Studio folder |
buildaudienceactivity | Build audience activity folder |
campaign | Campaign folder |
content | My contents folder |
dataextension | Data extensions folder |
document | My documents folder |
email | My emails folder |
group | My groups folder |
hidden | Hidden items folder |
image | My images folder |
job | My tracking folder |
list | My lists folder |
livecontent | Live content folder |
media | Portfolio folder |
microsite | Microsites folder |
micrositelayout | Microsite layouts folder |
filteractivity | Filter activity folder |
filterdefinition | Data filters definition folder |
measure | Measures folder |
survey | My surveys folder |
message | Message folder |
mysubs | My subscribers folder |
organization | Organizations folder |
playbooks | Playbooks folder |
programs2 | My programs folder |
publication | My publication lists folder |
queryactivity | Query activity folder |
template | My templates folder |
ssjsactivity | SSJS Activity folder |
suppression_list | Suppression Lists folder |
triggered_send | Triggered sends folder |
triggered_send_journeybuilder | Journey Builder triggered sends folder |
userinitiatedsends | User-initiated sends folder |
To use this function, pass a JSON object that defines your search criteria. The structure of the JSON object differs based on whether you want to perform a simple search or a complex one.
In a simple search, the JSON object contains the Property, SimpleOperator, and Value properties. This example returns a list of folders that belong to a parent folder named RewardsProgram.
In a complex search, the JSON object contains LeftOperand and RightOperand objects and a LogicalOperator property. The LeftOperand and RightOperand objects each contain a set of Property, SimpleOperator, and Value properties.
This example returns a list of folders in the My Images folder with names that begin with the text "LoyaltyRewards" followed by zero or more other characters.
Whether you perform a simple or complex search, the structure of the result is the same. The result is a JSON array that contains folder objects. Each folder object also contains an object that describes the properties of the parent folder.